DEV Community: Matt Raible

A Delightful Trip to Devnexus

Matt Raible — Wed, 22 May 2024 15:21:06 +0000

Devnexus is one of my favorite conferences in the world. I have many fond memories of attending over the years and some awkward ones, too. My first memory is when Micah Silverman and I worked at a Stormpath booth there in February 2017. Okta had just acquihired us and we weren't allowed to talk about it. We encouraged folks to sign up for our service even though we knew signups would shut down at the end of the week.

It's funny how life comes full circle. My employment with Okta officially ended the week before this year's Devnexus. I tried to cancel my talk when I first got the news, but Vincent and Pratik convinced me to go, and I knew it would be good for networking. I'm glad I did because I had a blast! It all started on Monday, April 8th.

// Detect dark theme var iframe = document.getElementById('tweet-1777354136201126385-523'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1777354136201126385&theme=dark" }

I was in a tremendously good mood when I took this photo. I was sporting a new DU hat in anticipation of their NCAA Frozen Four victory the following weekend. And I was on my way to what seemed like a college reunion. I've been a part of the Java community for over 20 years, and many of the speakers are old friends whom I've made a lot of memories with.

Tuesday, April 9

The first day started off with a JUG Leaders Summit. The two presentations I really enjoyed were from Jorge Cajas and Ari Waller. Jorges talked about getting students and younger people involved in JUGs (Java User Groups) and encouraged beginner talks.

// Detect dark theme var iframe = document.getElementById('tweet-1777692344076156988-829'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1777692344076156988&theme=dark" }

The Denver JUG used to have two talks at every meeting. The first was a basic concepts talk, and the second was more advanced. Over the years, we did away with the first talk in favor of one main talk and more networking afterward. Jorges pointed out we often expect developers to know Java frameworks when many of the younger developers have never used them.

Ari talked about an AJUG initiative to support qualified global JUGs by providing a paid Meetup Pro account. This is also part of an effort to bring visibility to the greater Java community and it will be called the Devnexus Java Community Meetup Pro Network. I'll update this post when I have more information.

That afternoon, we had a Java Champions Summit. We discussed many topics, and we've since scheduled more time to talk virtually later this month. The photo below from Ken Fogel captures that we had a lot of Java leaders in attendance!

Wednesday, April 10

Pratik and Vincent kicked off the <dev/>olution on Wednesday morning. Amazingly, they've been doing it for 20 years!

I did an interview with Baruch Sadogursky at Gradle's Build Propulsion Lab after the opening keynote. We talked about developer productivity, open source, Develocity, and JHipster.

I also did an interview with Melissa McKay at the DevOps Speakeasy. We talked about my session, Micro Frontends for Java Microservices.

That afternoon, Sharat Chander's keynote about moving Java forward together contained wisdom he learned from his father.

// Detect dark theme var iframe = document.getElementById('tweet-1778117887883968895-29'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1778117887883968895&theme=dark" }

I talked with Sean Phillips the night before. He dazzled me with his enthusiasm for fighting back against bad actors with his Trinity project. I was not disappointed during his talk and thoroughly enjoyed all my conversations with him and his lovely wife.

// Detect dark theme var iframe = document.getElementById('tweet-1778156667764408768-506'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1778156667764408768&theme=dark" }

Seeing so many old friends at the conference before the social activities that evening was awesome.

// Detect dark theme var iframe = document.getElementById('tweet-1778205643817816337-226'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1778205643817816337&theme=dark" }

Thursday, April 11

I prepped for my talk Thursday morning, practiced my demo, and dressed up as an old-fashioned Java developer. My talk had a full room and I finished right on time. The demo worked flawlessly, so I was quite pleased. You can find my presentation on Speaker Deck.

That afternoon, I hung out with Josh Long and met Chris Bono. We had cocktails at White Oak and had a fun time talking about Spring, life, and our fantastic children. From there, I reunited with former colleagues Brian Demers, Randall Degges, Micah Silverman, and others at Cuts Steakhouse. I sat next to Jonathan Schneider from OpenRewrite and learned a lot. I was impressed to learn that OpenRewrite is used to upgrade applications between major releases, and some folks have used it to migrate from one Java framework to another.

Friday, April 12

The conference ended on Thursday, and Friday was a designated Speaker Day. We gathered at Cabbagetown Park for a few hours of volleyball, reminiscing, and recovering from the week of intense social activities. That evening, we headed to The Painted Duck for some duckpin bowling. It was a lot harder than regular bowling, yet fun was had by all.

// Detect dark theme var iframe = document.getElementById('tweet-1778928398397489350-618'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1778928398397489350&theme=dark" }

If you ever get a chance to attend or speak at Devnexus, I highly recommend it. It's a well-run show, and the community vibe is wonderful. Thank you, Pratik, Vincent, and the Atlanta JUG team!

Funemployment 2024

Matt Raible — Tue, 07 May 2024 21:54:23 +0000

On February 1, I woke up to an unexpected email from my employer.

// Detect dark theme var iframe = document.getElementById('tweet-1753070760237858957-89'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1753070760237858957&theme=dark" }

I laughed out loud at first, then smiled and felt an overwhelming sense of freedom. I went through a wide range of emotions that morning, but despair was never one of them. As a high performer on my team, I did not expect to be laid off. However, looking back over the last several months, there were a few indicators that it might happen.

I quickly realized the bright side of my situation:

It was the middle of ski season, and
I had nothing to do.

I was laid off on a Thursday morning and was scheduled to leave for Jfokus that Saturday. I was supposed to do a workshop, a talk, and help at the Okta booth. Since my talks used Okta products and it'd be weird to represent a company that just laid you off, I had to back out of the conference. It just didn't feel right.

The reason I had nothing to do is all of the activities I did on my computer were Okta-related. I didn't even have a personal computer. I did all my work on the company laptop and all of my open source contributions had a relationship to my work.

I received many inquiries from my tweet above and my LinkedIn post with the same message. I told everyone I was going to take a couple weeks to process things and skiing was my top priority. I've been unemployed in the past, but I never received any sort of severance, let alone one that lasted for months. I knew that this was the opportunity of a lifetime. Funemployment is the condition of a person who takes advantage of being out of a job to have the time of their life. This is my funemployment story.

First, I headed to Winter Park to stay at our Ski Chalet. There were several powder days and a few friends that joined in the festivities.

I returned home that Friday to attend a local Chi Phi Fraternity reunion in downtown Denver.

Then, Trish and I enjoyed a Pitbull concert at Ball Arena and I sent back my laptop and stickers.

My parents came to visit for 10 days in mid-February. We hung out with Abbie and Jack a few nights, including a night at Casa Bonita, the self-proclaimed "Greatest Restaurant in the World!"

I got a couple more powder days in at the end of February.

My sister proposed we go to Spring Training in Arizona and I leapt at the opportunity. I'd never been before and it seemed like fun. I highly recommend it if you've never been, especially the one in Scottsdale, Arizona. There are several baseball games every day, they're all within driving distance, and the weather is gorgeous.

Before flying home on March 5th, I made sure to announce my plans for the rest of the month. All these trips had been planned for months, except for Spring Training.

// Detect dark theme var iframe = document.getElementById('tweet-1765063903447527594-314'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1765063903447527594&theme=dark" }

My friend Chris Morse's birthday at Sugarbush was outstanding. I expected a bit more snow, but we had fun anyway.

Then, I joined Trish in Naples, Florida for St. Paddy's Day with her family.

We teamed up with Bruce and Janene Snyder for Spring Break. They're empty nesters like us, our kids are both at CU, and shared the same Spring Break. When we originally planned our trip to Cabo San Lucas, we expected our kids might join us. We didn't mind going without them when they declined.

After a week in Cabo, we returned to Colorado and spent the weekend skiing at Winter Park and Steamboat.

You can find more photos on Flickr in my Funemployment 2024 album.

April arrived quickly and I aggressively started looking for my next gig. By aggressively, I mean I updated my resume and started applying to jobs the old-fashioned way. I haven't needed a resume since 2007. It's nostalgic to look back at the last one I used in 2007. For the last decade and a half, I've relied on my reputation and LinkedIn profile. You can find my current resume here.

Throughout April, I've been talking with several companies. I also attended Devnexus and did a road trip to speak at the Utah JUG. Both trips deserve their own blog posts, so watch for those soon. In the meantime, if you're hiring exceptional software engineers or developer advocates, I'd love to chat!

Java Microservices with Spring Boot and Spring Cloud

Matt Raible — Thu, 11 Jan 2024 20:11:00 +0000

Adopting a microservices architecture provides unique opportunities to add failover and resiliency to your systems so your components can gracefully handle load spikes and errors. Microservices make change less expensive, too. They can also be a good idea when you have a large team working on a single product. You can break up your project into components that can function independently. Once components can operate independently, they can be built, tested, and deployed separately. This gives an organization and its teams the agility to develop and deploy quickly.

Java is an excellent language with a vast open source ecosystem for developing a microservice architecture. In fact, some of the biggest names in our industry use Java and contribute to its ecosystem. Have you ever heard of Netflix, Amazon, or Google? What about eBay, Twitter, and LinkedIn? Yes, web-scale companies handling incredible traffic are doing it with Java.

Implementing a microservices architecture in Java isn't for everyone. For that matter, implementing microservices, in general, isn't often needed. Most companies do it to scale their people, not their systems. Even Martin Fowler's original blog post on Microservices recommends against it:

One reasonable argument we've heard is that you shouldn't start with a microservices architecture. Instead begin with a monolith, keep it modular, and split it into microservices once the monolith becomes a problem.

The Java ecosystem has some well-established patterns for developing microservice architectures. If you're familiar with Spring, you'll feel right at home developing with Spring Boot and Spring Cloud. Since that's one of the quickest ways to get started, I figured I'd walk you through a quick example.

This example contains a microservice with a REST API that returns a list of cool cars. It uses Netflix Eureka for service discovery, WebClient for remote communication, and Spring Cloud Gateway to route requests to the microservice. It integrates Spring Security and OAuth 2.0, so only authenticated users can access the API gateway and microservice. It also uses Resilience4j to add fault tolerance to the gateway.

Here is a diagram showing the overall infrastructure:

Create Java Microservices with Spring Boot and Spring Cloud

I like to show developers how to build everything from scratch. Today, I'm going to take a different approach. First, I'll show you how to get the completed example working. Then, I'll explain how I created everything and the trials and tribulations I encountered along the way.

You can start by cloning the @oktadev/auth0-java-microservices-examples repository.

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

There are two directories in this repository that pertain to this tutorial:

spring-boot-gateway-webflux: a Spring Boot microservice architecture with Spring Cloud Gateway and Spring WebFlux.
spring-boot-gateway-mvc: a Spring Boot microservice architecture with Spring Cloud Gateway and Spring MVC.

Each directory contains three projects:

discovery-service: a Netflix Eureka server used for service discovery.
car-service: a simple Car Service that uses Spring Data REST to serve up a REST API of cars.
api-gateway: an API gateway with a /cool-cars endpoint that talks to the car service and filters out cars that aren't cool (in my opinion, of course).

The configuration for the WebFlux and MVC implementations is the same, so choose one and follow along.

You can also watch a demo of the WebFlux example in the screencast below.

Run a Secure Spring Boot Microservice Architecture

To run the example, you must install the Auth0 CLI and create an Auth0 account. If you don't have an Auth0 account, sign up for free. I recommend using SDKMAN! to install Java 17+ and HTTPie for making HTTP requests.

First, start the discovery service:

cd discovery-service
./gradlew bootRun

Before you can start the API gateway project, you'll need to configure the API gateway to use your Auth0 account.

Open a terminal and run auth0 login to configure the Auth0 CLI to get an API key for your tenant. Then, run auth0 apps create to register an OpenID Connect (OIDC) app with the appropriate URLs:

auth0 apps create \
  --name "Kick-Ass Cars" \
  --description "Microservices for Cool Cars" \
  --type regular \
  --callbacks http://localhost:8080/login/oauth2/code/okta \
  --logout-urls http://localhost:8080 \
  --reveal-secrets

Copy api-gateway/.env.example to .env and edit it to contain the values from the command above.

OKTA_OAUTH2_ISSUER=https://<your-auth0-domain>/
OKTA_OAUTH2_CLIENT_ID=
OKTA_OAUTH2_CLIENT_SECRET=
OKTA_OAUTH2_AUDIENCE=https://<your-auth0-domain>/api/v2/

At startup, these properties will be read using spring-dotenv.

Run ./gradlew bootRun to start the API gateway, or use your IDE to run it.

Copy car-service/.env.example to .env and update its values.

OKTA_OAUTH2_ISSUER=https://<your-auth0-domain>/
OKTA_OAUTH2_AUDIENCE=https://<your-auth0-domain>/api/v2/

Start it with ./gradlew bootRun and open http://localhost:8080 in your favorite browser. You'll be redirected to Auth0 to log in:

After authenticating, you'll see your name in lights! ✨

You can navigate to the following URLs in your browser for different results:

http://localhost:8080/print-token: prints access token to the terminal
http://localhost:8080/cool-cars: returns a list of cool cars
http://localhost:8080/home: proxies request to the car service and prints JWT claims in this application's terminal

You can see the access token's contents by copying/pasting it into jwt.io. You can also access the car service directly using it.

TOKEN=<access-token>
http :8090/cars Authorization:"Bearer $TOKEN"

Pretty cool, eh? 😎

My Developer Story with Spring Boot and Spring Cloud

A few years ago, I created an example similar to this one with Spring Boot 2.2. It used Feign for remote connectivity, Zuul for routing, Hystrix for failover, and Spring Security for OAuth. The September 2023 version of Spring Cloud has Spring Cloud OpenFeign for remote connectivity, Spring Cloud Gateway for routing, and Resilience4j for fault tolerance.

Okta also now has an Okta Spring Boot starter. I didn't use it in my first experiment, but I'm a big fan of it after the last few years! It dramatically simplifies configuration and makes securing your apps with OAuth 2.0 and OIDC easy. It's a thin wrapper around Spring Security's resource server, OAuth client, and OIDC features. Not only that, but it works with Okta Workforce Identity, Okta Customer Identity (aka Auth0), and even Keycloak.

I created all of these applications using start.spring.io's REST API and HTTPie.

https start.spring.io/starter.tgz bootVersion==3.2.0 \
  artifactId==discovery-service name==eureka-service \
  dependencies==cloud-eureka-server baseDir==discovery-service | tar -xzvf -

https start.spring.io/starter.tgz bootVersion==3.2.0 \
  artifactId==car-service name==car-service baseDir==car-service \
  dependencies==actuator,cloud-eureka,data-jpa,data-rest,postgresql,web,validation,devtools,docker-compose,okta | tar -xzvf -

https start.spring.io/starter.tgz bootVersion==3.2.0 \
  artifactId==api-gateway name==api-gateway baseDir==api-gateway \
  dependencies==cloud-eureka,cloud-feign,data-rest,web,okta | tar -xzvf -

You might notice the api-gateway project doesn't have cloud-gateway as a dependency. That's because I started without it and didn't add it until I needed to proxy requests by path.

In the code listings below, all package and import statements have been removed for brevity. You can find the complete source code in the auth0-java-microservices-examples repository.

Service Discovery with Netflix Eureka

The discovery-service is configured the same as you would most Eureka servers. It has an @EnableEurekaServer annotation on its main class and properties that set its port and turn off discovery.

server.port=8761
eureka.client.register-with-eureka=false
eureka.client.fetch-registry=false

The car-service and api-gateway projects are configured similarly. Both have a unique name defined, and car-service is configured to run on port 8090 so it doesn't conflict with 8080:

# car-service/src/main/resources/application.properties
server.port=8090
spring.application.name=car-service

# api-gateway/src/main/resources/application.properties
spring.application.name=api-gateway

@EnableDiscoveryClient annotates the main class in both car service and API gateway.

Build a Java Microservice with Spring Data REST

The car-service provides a REST API that lets you CRUD (Create, Read, Update, and Delete) cars. It creates a default set of cars when the application loads using an ApplicationRunner bean:

// car-service/src/main/java/com/example/carservice/CarServiceApplication.java
@EnableDiscoveryClient
@SpringBootApplication
public class CarServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(CarServiceApplication.class, args);
    }

    @Bean
    ApplicationRunner init(CarRepository repository) {
        repository.deleteAll();
        return args -> {
            Stream.of("Ferrari", "Jaguar", "Porsche", "Lamborghini", "Bugatti",
                "AMC Gremlin", "Triumph Stag", "Ford Pinto", "Yugo GV").forEach(name -> {
                repository.save(new Car(name));
            });
            repository.findAll().forEach(System.out::println);
        };
    }
}

The CarRepository interface makes persisting and fetching cars from the database easy:

// car-service/src/main/java/com/example/carservice/data/CarRepository.java
@RepositoryRestResource
public interface CarRepository extends JpaRepository<Car, Long> {
}

The Car class is a simple JPA entity with an id and name property. Spring Boot will see PostgreSQL on its classpath and autoconfigure connectivity. A compose.yaml file exists in the root directory to start a PostgreSQL instance using Docker Compose:

services:
  postgres:
    image: 'postgres:latest'
    environment:
      - 'POSTGRES_DB=mydatabase'
      - 'POSTGRES_PASSWORD=secret'
      - 'POSTGRES_USER=myuser'
    ports:
      - '5432'

Spring Boot added Docker Compose support in version 3.1. This means that if you add the following dependency to your build.gradle, it'll look for a compose.yaml (or docker-compose.yaml) file in the root directory and start it when you run ./gradlew bootRun:

developmentOnly 'org.springframework.boot:spring-boot-docker-compose'

Finally, the application.properties has a setting to create the database automatically:

spring.jpa.hibernate.ddl-auto=update

Connect to Java Microservices with Spring Cloud OpenFeign

Next, I configured OpenFeign in the api-gateway project to connect to the car service and its /cars endpoint. Then, I mapped a Car record to the JSON that's returned. I exposed it as a /cool-cars endpoint:

// api-gateway/src/main/java/com/example/apigateway/ApiGatewayApplication.java
@EnableFeignClients
@EnableDiscoveryClient
@SpringBootApplication
public class ApiGatewayApplication {

    public static void main(String[] args) {
        SpringApplication.run(ApiGatewayApplication.class, args);
    }
}

record Car(String name) {
}

@FeignClient("car-service")
interface CarClient {

    @GetMapping("/cars")
    CollectionModel<Car> readCars();
}

@RestController
class CoolCarController {

    private final CarClient carClient;

    public CoolCarController(CarClient carClient) {
        this.carClient = carClient;
    }

    @GetMapping("/cool-cars")
    public Collection<Car> coolCars() {
        return carClient.readCars()
                .getContent()
                .stream()
                .filter(this::isCool)
                .collect(Collectors.toList());
    }

    private boolean isCool(Car car) {
        return !car.name().equals("AMC Gremlin") &&
                !car.name().equals("Triumph Stag") &&
                !car.name().equals("Ford Pinto") &&
                !car.name().equals("Yugo GV");
    }
}

This worked great, but I still wanted to proxy /home to the downstream car service.

Add Routing with Spring Cloud Gateway

When I first wrote this tutorial with Spring Boot 3.1 and Spring Cloud 2022.0.4, Spring Cloud Gateway only had a WebFlux API. Since Spring Cloud 2023.0.0, it has a Spring MVC API too! This means you can use it with Spring MVC or Spring WebFlux.

Proxy Requests by Path with Spring MVC

I added spring-cloud-starter-gateway-mvc as a dependency to the api-gateway project and added the following to a new api-gateway/src/main/resources/application.yml file:

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
      mvc:
        routes:
          - id: car-service
            uri: lb://car-service
            predicates:
              - Path=/home/**

With this configuration, I could access the car service directly at http://localhost:8090/cars and through the gateway at http://localhost:8080/cool-cars.

To add failover with Spring Cloud Circuit Breaker, I added it as a dependency:

implementation 'org.springframework.cloud:spring-cloud-starter-circuitbreaker-resilience4j'

Then, I enabled it in application.properties:

spring.cloud.openfeign.circuitbreaker.enabled=true

I updated the CarClient interface in ApiGatewayApplication to have a fallback that returns an empty list of cars if the car service is unavailable.

@FeignClient(name = "car-service", fallback = Fallback.class)
interface CarClient {

    @GetMapping("/cars")
    CollectionModel<Car> readCars();

}

@Component
class Fallback implements CarClient {

    @Override
    public CollectionModel<Car> readCars() {
        return CollectionModel.empty();
    }
}

Proxy Requests by Path with WebFlux

Getting everything to work with Spring MVC and Spring Cloud Gateway didn't take long. Using Spring WebFlux required a bit more work.

I immediately discovered that adding spring-cloud-starter-gateway as a dependency caused issues. First, I had Spring MVC in my classpath, and Spring Cloud Gateway uses WebFlux. WebFlux recommends using WebClient over Feign. I decided to switch to WebClient.

I had to remove the following dependencies from my original api-gateway project:

implementation 'org.springframework.boot:spring-boot-starter-data-rest'
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.cloud:spring-cloud-starter-openfeign'

And add Spring Cloud Gateway with Resilience4j dependencies:

implementation 'org.springframework.cloud:spring-cloud-starter-circuitbreaker-reactor-resilience4j'
implementation 'org.springframework.cloud:spring-cloud-starter-gateway'

Then, I moved CoolCarController to its own class and re-implemented it with WebClient:

// api-gateway/src/main/java/com/example/apigateway/web/CoolCarController.java
@RestController
class CoolCarController {

    Logger log = LoggerFactory.getLogger(CoolCarController.class);

    private final WebClient.Builder webClientBuilder;
    private final ReactiveCircuitBreaker circuitBreaker;

    public CoolCarController(WebClient.Builder webClientBuilder,
                             ReactiveCircuitBreakerFactory circuitBreakerFactory) {
        this.webClientBuilder = webClientBuilder;
        this.circuitBreaker = circuitBreakerFactory.create("circuit-breaker");
    }

    record Car(String name) {
    }

    @GetMapping("/cool-cars")
    public Flux<Car> coolCars() {
        return circuitBreaker.run(
            webClientBuilder.build()
                .get().uri("http://car-service/cars")
                .retrieve().bodyToFlux(Car.class)
                .filter(this::isCool),
            throwable -> {
                log.warn("Error making request to car service", throwable);
                return Flux.empty();
            });
    }

    private boolean isCool(Car car) {
        return !car.name().equals("AMC Gremlin") &&
            !car.name().equals("Triumph Stag") &&
            !car.name().equals("Ford Pinto") &&
            !car.name().equals("Yugo GV");
    }
}

In order to inject the WebClient.Builder, I had to create a WebClientConfiguration class:

// api-gateway/src/main/java/com/example/apigateway/config/WebClientConfiguration.java
@Configuration
public class WebClientConfiguration {

    @Bean
    @LoadBalanced
    public WebClient.Builder webClientBuilder() {
        return WebClient.builder();
    }
}

In the car-service project, I had to switch from using Spring Data REST to handling it with a @RestController and @GetMapping annotation. I removed the @RepositoryRestResource annotation from CarRepository and added a CarController class:

// car-service/src/main/java/com/example/carservice/web/CarController.java
@RestController
class CarController {

    private final CarRepository repository;

    public CarController(CarRepository repository) {
        this.repository = repository;
    }

    @GetMapping("/cars")
    public List<Car> getCars() {
        return repository.findAll();
    }
}

NOTE: I did try to use Spring HATEOAS but ran into an issue when using it with the Okta Spring Boot starter.

To proxy /home to the downstream microservice, I added a api-gateway/src/main/resources/application.yml file to configure Spring Cloud Gateway to enable service discovery and specify routes:

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
      routes:
        - id: car-service
          uri: lb://car-service
          predicates:
            - Path=/home/**

At this point, I could access the car service directly at http://localhost:8090/cars and through the gateway at http://localhost:8080/cool-cars.

Secure Spring Boot Microservices with OAuth 2.0 and OIDC

To configure the Okta Spring Boot starter, there are a few properties in the api-gateway project's application.properties file:

okta.oauth2.issuer=${OKTA_OAUTH2_ISSUER}
okta.oauth2.client-id=${OKTA_OAUTH2_CLIENT_ID}
okta.oauth2.client-secret=${OKTA_OAUTH2_CLIENT_SECRET}
okta.oauth2.audience=${OKTA_OAUTH2_AUDIENCE}

The car-service is configured as an OAuth resource server and has the following properties in its application.properties file:

okta.oauth2.issuer=${OKTA_OAUTH2_ISSUER}
okta.oauth2.audience=${OKTA_OAUTH2_AUDIENCE}

The variables are read from the .env file in each project's root directory.

Fetch an Access Token as a JWT

When I first got things working, I was able to log in to the gateway, but when I tried to connect to the downstream microservice, it said the JWT was invalid. For this reason, I added a /print-token endpoint to the gateway that prints the access token to the console.

NOTE: The code in this section is for the WebFlux version. The MVC version is in the next section.

// api-gateway/src/main/java/com/example/apigateway/web/HomeController.java
@RestController
class HomeController {

    @GetMapping("/")
    public String howdy(@AuthenticationPrincipal OidcUser user) {
        return "Hello, " + user.getFullName();
    }

    @GetMapping("/print-token")
    public String printAccessToken(@RegisteredOAuth2AuthorizedClient("okta")
                                   OAuth2AuthorizedClient authorizedClient) {

        var accessToken = authorizedClient.getAccessToken();

        System.out.println("Access Token Value: " + accessToken.getTokenValue());
        System.out.println("Token Type: " + accessToken.getTokenType().getValue());
        System.out.println("Expires At: " + accessToken.getExpiresAt());

        return "Access token printed";
    }
}

Using jwt.io, I verified that it wasn't a valid JWT. I thought about trying to implement Spring Security's opaque token support, but discovered Auth0 doesn't have an /instropection endpoint. This makes it impossible to use opaque tokens with Auth0.

The good news is I figured out a workaround! If you pass a valid audience parameter to Auth0, you'll get a JWT for the access token. I logged an issue to improve the Okta Spring Boot starter and added a SecurityConfiguration class to solve the problem in the meantime.

// api-gateway/src/main/java/com/example/apigateway/config/SecurityConfiguration.java
@Configuration
public class SecurityConfiguration {

    @Value("${okta.oauth2.audience:}")
    private String audience;

    private final ReactiveClientRegistrationRepository clientRegistrationRepository;

    public SecurityConfiguration(ReactiveClientRegistrationRepository clientRegistrationRepository) {
        this.clientRegistrationRepository = clientRegistrationRepository;
    }

    @Bean
    public SecurityWebFilterChain filterChain(ServerHttpSecurity http) throws Exception {
        http
            .authorizeExchange(authz -> authz
                .anyExchange().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .authorizationRequestResolver(
                    authorizationRequestResolver(this.clientRegistrationRepository)
                )
            );
        return http.build();
    }

    private ServerOAuth2AuthorizationRequestResolver authorizationRequestResolver(
        ReactiveClientRegistrationRepository clientRegistrationRepository) {

        var authorizationRequestResolver =
            new DefaultServerOAuth2AuthorizationRequestResolver(clientRegistrationRepository);
        authorizationRequestResolver.setAuthorizationRequestCustomizer(
            authorizationRequestCustomizer());

        return authorizationRequestResolver;
    }

    private Consumer<OAuth2AuthorizationRequest.Builder> authorizationRequestCustomizer() {
        return customizer -> customizer
            .additionalParameters(params -> params.put("audience", audience));
    }
}

To make Spring Cloud Gateway pass the access token downstream, I added TokenRelay to its default filters in application.yml:

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
      default-filters:
        - TokenRelay
      routes: ...

I updated the WebClientConfiguration class to configure WebClient to include the access token with its requests:

// api-gateway/src/main/java/com/example/apigateway/config/WebClientConfiguration.java
@Configuration
public class WebClientConfiguration {

    @Bean
    @LoadBalanced
    public WebClient.Builder webClientBuilder(ReactiveClientRegistrationRepository clientRegistrations,
                                              ServerOAuth2AuthorizedClientRepository authorizedClients) {
        var oauth = new ServerOAuth2AuthorizedClientExchangeFilterFunction(clientRegistrations, authorizedClients);
        oauth.setDefaultClientRegistrationId("okta");
        return WebClient
            .builder()
            .filter(oauth);
    }

}

Spring Cloud Gateway MVC and OAuth 2.0

To get the Spring Cloud Gateway MVC example working with OAuth 2.0, I had to add a SecurityConfiguration class to pass an audience parameter to Auth0:

// api-gateway/src/main/java/com/example/apigateway/config/SecurityConfiguration.java
@Configuration
public class SecurityConfiguration {

    @Value("${okta.oauth2.audience:}")
    private String audience;

    private final ClientRegistrationRepository clientRegistrationRepository;

    public SecurityConfiguration(ClientRegistrationRepository clientRegistrationRepository) {
        this.clientRegistrationRepository = clientRegistrationRepository;
    }

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authorize -> authorize
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .authorizationEndpoint(authorization -> authorization
                    .authorizationRequestResolver(
                        authorizationRequestResolver(this.clientRegistrationRepository)
                    )
                )
            );
        return http.build();
    }

    private OAuth2AuthorizationRequestResolver authorizationRequestResolver(
        ClientRegistrationRepository clientRegistrationRepository) {

        DefaultOAuth2AuthorizationRequestResolver authorizationRequestResolver =
            new DefaultOAuth2AuthorizationRequestResolver(
                clientRegistrationRepository, "/oauth2/authorization");
        authorizationRequestResolver.setAuthorizationRequestCustomizer(
            authorizationRequestCustomizer());

        return authorizationRequestResolver;
    }

    private Consumer<OAuth2AuthorizationRequest.Builder> authorizationRequestCustomizer() {
        return customizer -> customizer
            .additionalParameters(params -> params.put("audience", audience));
    }
}

Spring Cloud Gateway MVC 2023.0.0 doesn't allow you to configure a TokenRelay filter in YAML, so I added a RouterFunction bean to add it.

// api-gateway/src/main/java/com/example/apigateway/ApiGatewayApplication.java
public class ApiGatewayApplication {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsLoadBalancer() {
        return route("car-service")
            .route(path("/home/**"), http())
            .filter(lb("car-service"))
            .filter(tokenRelay())
            .build();
    }

    public static void main(String[] args) {
        SpringApplication.run(ApiGatewayApplication.class, args);
    }
}

Thanks for the help with this code, Spencer Gibb! 🙌

The updated application.yml file looks as follows after removing its mvc configuration.

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true

The last thing I needed to configure was OAuth integration for OpenFeign. I added the following properties to application.properties:

spring.cloud.openfeign.oauth2.enabled=true
spring.cloud.openfeign.oauth2.clientRegistrationId=okta

I removed the spring.cloud.openfeign.circuitbreaker.enabled property because I could not get it to work with Spring MVC. If you know how to make it work, please let me know in the comments!

Spring Boot Microservices and Refresh Tokens

In my previous Spring Boot 2.2 example, I couldn't get refresh tokens to work. I was able to get them to work this time! I changed the default scopes in api-gateway to request a refresh token using the offline_access scope:

# .env
OKTA_OAUTH2_AUDIENCE=https://fast-expiring-api
OKTA_OAUTH2_SCOPES=openid,profile,email,offline_access

And added a property to application.properties to read it:

# src/main/resources/application.properties
okta.oauth2.scopes=${OKTA_OAUTH2_SCOPES}

Then, I created an API in Auth0 called fast-expiring-api and set it to expire in 30 seconds:

auth0 apis create --name fast-expiring --identifier https://fast-expiring-api \
  --token-lifetime 30 --offline-access --no-input

If you do the same, you can restart the API gateway and go to http://localhost:8080/print-token to see your access token. You can copy the expired time to timestamp-converter.com to see when it expires in your local timezone. Wait 30 seconds and refresh the page. You'll see a request for a new token and an updated Expires At timestamp in your terminal.

The Okta Spring Boot starter and Keycloak

If you find yourself in a situation where you don't have an internet connection, it can be handy to run Keycloak locally in a Docker container. Since the Okta Spring Boot starter is a thin wrapper around Spring Security, it works with Keycloak, too.

In my experience, Spring Security's OAuth support works with any OAuth 2.0-compliant server. The Okta Spring Boot starter does validate the issuer to ensure it's an Okta URL, so you must use Spring Security's properties instead of the okta.oauth2.* properties when using Keycloak.

An easy way to get a pre-configured Keycloak instance is to use JHipster's jhipster-sample-app-oauth2 application. It gets updated with every JHipster release. You can clone it with the following command:

git clone https://github.com/jhipster/jhipster-sample-app-oauth2.git --depth=1
cd jhipster-sample-app-oauth2

Then, start its Keycloak instance:

docker compose -f src/main/docker/keycloak.yml up -d

You can configure the api-gateway to use Keycloak by removing the okta.oauth2.* properties and using Spring Security's in application.properties:

spring.security.oauth2.client.provider.okta.issuer-uri=http://localhost:9080/realms/jhipster
spring.security.oauth2.client.registration.okta.client-id=web_app
spring.security.oauth2.client.registration.okta.client-secret=web_app
spring.security.oauth2.client.registration.okta.scope=openid,profile,email,offline_access

The car-service requires similar changes in its application.properties file:

spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:9080/realms/jhipster
spring.security.oauth2.resourceserver.jwt.audiences=account

Restart both apps, open http://localhost:8080, and you'll be able to log in with Keycloak:

Use admin/admin for credentials, and you can access http://localhost:8080/cool-cars as you did before:

Stay secure with Spring Boot and Spring Cloud!

I hope you liked this tour of how to build Java microservice architectures with Spring Boot and Spring Cloud. You learned how to build everything with minimal code and then configure it to be secure with Spring Security, OAuth 2.0, OIDC, and Auth0 by Okta.

You can find all the code shown in this tutorial on GitHub in the @oktadev/auth0-java-microservices-examples repository. The OpenFeign example with Spring MVC is in the spring-boot-gateway-mvc directory. The Spring Cloud Gateway with WebFlux is in spring-boot-gateway-webflux. The Keycloak example is in the keycloak branch.

If you liked this post, you might enjoy these related posts:

We've also published some new labs about securing Spring Boot in our Developer Center. They're great if you like to learn by doing!

Please follow us on Twitter @oktadev and subscribe to our YouTube channel for more Spring Boot and microservices knowledge.

You can also sign up for our developer newsletter to stay updated on everything Identity and Security.

Build a Beautiful CRUD App with Spring Boot and Angular

Matt Raible — Wed, 30 Aug 2023 02:12:46 +0000

Angular is one of my favorite frameworks for building single-page applications (SPAs). As a Java developer, its separation of components, services, and pipes made a lot of sense to me. It's a web framework that allows you to declaratively describe your UI by creating small, reusable components. I believe it was a huge influencer in TypeScript's popularity. It's also backed by Google, which means it will likely be around for a long time.

I like to build CRUD (create, read, update, and delete) apps to understand frameworks. I think they show a lot of the base functionality you need when creating an app. Once you complete the basics of CRUD, most of the integration work is finished, and you can move on to implementing the necessary business logic.

In this tutorial, you'll learn how to build a secure CRUD app with Spring Boot and Angular. The final will result will use OAuth 2.0 authorization code flow and package the Angular app in the Spring Boot app for distribution as a single artifact. At the same time, I'll show you how to keep Angular's productive workflow when developing locally.

You'll need to install several tools to follow along with this tutorial.

Prerequisites:

You can also watch a demo of the completed example in the screencast below:

Configure and Run a Spring Boot and Angular App

I'm a frequent speaker at conferences and Java User Groups (JUGs) around the world. I've been a Java developer for 20+ years and ❤️ the Java community. I've found that speaking at JUGs is a great way to interact with the community and get raw feedback on presentations.

// Detect dark theme var iframe = document.getElementById('tweet-1623190784072720386-997'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1623190784072720386&theme=dark" }

Why am I telling you this? Because I thought it'd be fun to create a "JUG Tours" app that allows you to create/edit/delete JUGs and view upcoming events.

I realize that taking 20 minutes to build this app can be cumbersome, so I've already built it in @oktadev/auth0-spring-boot-angular-crud-example. The project uses Spring Boot 3.2.0 and Angular 17. I hope this helps you clone, configure, and run! Seeing something running is such a joyful experience. 🤗

git clone https://github.com/oktadev/auth0-spring-boot-angular-crud-example jugtours
cd jugtours

Open a terminal window and run auth0 login to configure the Auth0 CLI to get an API key for your tenant. Then, run auth0 apps create to register this app with the appropriate URLs:

auth0 apps create \
  --name "Bootiful Angular" \
  --description "Spring Boot + Angular = ❤️" \
  --type regular \
  --callbacks http://localhost:8080/login/oauth2/code/okta,http://localhost:4200/login/oauth2/code/okta \
  --logout-urls http://localhost:8080,http://localhost:4200 \
  --reveal-secrets

Copy the outputted values from this command into a new .okta.env file:

export OKTA_OAUTH2_ISSUER=https://<your-auth0-domain>/
export OKTA_OAUTH2_CLIENT_ID=<your-client-id>
export OKTA_OAUTH2_CLIENT_SECRET=<your-client-secret>

If you're on Windows, use set instead of export to set these environment variables, and name the file .okta.env.bat:

set OKTA_OAUTH2_ISSUER=https://<your-auth0-domain>/
set OKTA_OAUTH2_CLIENT_ID=<your-client-id>
set OKTA_OAUTH2_CLIENT_SECRET=<your-client-secret>

Then, run source .okta.env (or .okta.env.bat on Windows) to set these environment variables in your current shell.

Finally, run ./mvnw (or mvnw on Windows) to start the app.

source .okta.env # run .okta.env.bat on Windows
./mvnw -Pprod # use mvnw -Pprod on Windows

To view the app, you can then open http://localhost:8080 in your favorite browser.

Click Login, and you'll be prompted to log in with Auth0. You'll also be asked for consent. This is because the app is requesting access to your profile and email address. Click Accept to continue.

Once you're authenticated, you'll see a link to manage your JUG Tours.

You should be able to add new groups and events, as well as edit and delete them.

Verify Cypress end-to-end tests pass

You can verify everything works by executing the Cypress tests that are included in the project. First, add environment variables for your credentials to the .okta.env (or .okta.env.bat) file you created earlier.

export CYPRESS_E2E_DOMAIN=<your-auth0-domain> # use the raw value, no https prefix
export CYPRESS_E2E_USERNAME=<your-email>
export CYPRESS_E2E_PASSWORD=<your-password>

Then, run source .okta.env (or .okta.env.bat on Windows) to set these environment variables.

Finally, run npm run e2e to start the app and run the Cypress tests.

cd app
npm run e2e

Pretty slick, don't you think? 🤠

Read on if you'd like to see how I created this app!

Create a Java REST API with Spring Boot

The easiest way to create a new Spring Boot app is to navigate to start.spring.io and make the following selections:

Project: Maven Project
Group: com.okta.developer
Artifact: jugtours
Dependencies: JPA, H2, Web, Validation

Click Generate Project, expand jugtours.zip after downloading, and open the project in your favorite IDE.

You can also use this link or HTTPie to create the project from the command line:

https start.spring.io/starter.tgz type==maven-project bootVersion==3.2.0 \
  dependencies==data-jpa,h2,web,validation \
  language==java platformVersion==17 \
  name==jugtours artifactId==jugtours \
  groupId==com.okta.developer packageName==com.okta.developer.jugtours \
  baseDir==jugtours | tar -xzvf -

Add a JPA domain model

Open the jugtours project in your favorite IDE. Create a src/main/java/com/okta/developer/jugtours/model directory and a Group.java class in it.

package com.okta.developer.jugtours.model;

import jakarta.persistence.*;
import jakarta.validation.constraints.NotNull;

import java.util.Set;

@Entity
@Table(name = "user_group")
public class Group {

    @Id
    @GeneratedValue
    private Long id;
    @NotNull
    private String name;
    private String address;
    private String city;
    private String stateOrProvince;
    private String country;
    private String postalCode;
    @ManyToOne(cascade = CascadeType.PERSIST)
    private User user;
    @OneToMany(fetch = FetchType.EAGER, cascade = CascadeType.ALL)
    private Set<Event> events;

    // JPA requires a default constructor
    public Group() {}

    public Group(String name) {
        this.name = name;
    }

    // getters and setters, equals, hashcode, and toString omitted for brevity
    // Why not Lombok? See https://twitter.com/mariofusco/status/1650439733212766208
    // Want Lombok anyway? See https://bit.ly/3HkaYMm and revert
}

Create an Event.java class in the same package.

package com.okta.developer.jugtours.model;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.ManyToMany;

import java.time.Instant;
import java.util.Set;

@Entity
public class Event {

    @Id
    @GeneratedValue
    private Long id;
    private Instant date;
    private String title;
    private String description;

    @ManyToMany
    private Set<User> attendees;

    public Event() {}

    public Event(Instant date, String title, String description) {
        this.date = date;
        this.title = title;
        this.description = description;
    }

    // you can generate the getters and setters using your IDE!
}

And a User.java class.

package com.okta.developer.jugtours.model;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

import java.util.Objects;

@Entity
@Table(name = "users")
public class User {

    @Id
    private String id;
    private String name;
    private String email;

    public User() {}

    public User(String id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    // getters and setters omitted for brevity
}

Create a GroupRepository.java to manage the group entity.

package com.okta.developer.jugtours.model;

import org.springframework.data.jpa.repository.JpaRepository;

import java.util.List;

public interface GroupRepository extends JpaRepository<Group, Long> {
    Group findByName(String name);
}

To load some default data, create an Initializer.java class in the com.okta.developer.jugtours package.

package com.okta.developer.jugtours;

import com.okta.developer.jugtours.model.Event;
import com.okta.developer.jugtours.model.Group;
import com.okta.developer.jugtours.model.GroupRepository;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

import java.time.Instant;
import java.util.Collections;
import java.util.stream.Stream;

@Component
class Initializer implements CommandLineRunner {

    private final GroupRepository repository;

    public Initializer(GroupRepository repository) {
        this.repository = repository;
    }

    @Override
    public void run(String... strings) {
        Stream.of("Utah JUG", "Dallas JUG", "Tampa JUG", "Nashville JUG", "Detroit JUG")
            .forEach(name -> repository.save(new Group(name)));

        Group jug = repository.findByName("Tampa JUG");
        Event e = new Event(Instant.parse("2024-04-24T18:00:00.000Z"),
            "What the Heck is OAuth?",
            "Learn how and where OAuth can benefit your applications.");
        jug.setEvents(Collections.singleton(e));
        repository.save(jug);

        repository.findAll().forEach(System.out::println);
    }
}

Start your app with mvn spring-boot:run, and you should see groups and events being created.

Add a GroupController.java class (in src/main/java/.../jugtours/web) that allows you to CRUD groups.

package com.okta.developer.jugtours.web;

import com.okta.developer.jugtours.model.Group;
import com.okta.developer.jugtours.model.GroupRepository;
import jakarta.validation.Valid;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.Collection;
import java.util.Optional;

@RestController
@RequestMapping("/api")
class GroupController {

    private final Logger log = LoggerFactory.getLogger(GroupController.class);
    private final GroupRepository groupRepository;

    public GroupController(GroupRepository groupRepository) {
        this.groupRepository = groupRepository;
    }

    @GetMapping("/groups")
    Collection<Group> groups() {
        return groupRepository.findAll();
    }

    @GetMapping("/group/{id}")
    ResponseEntity<?> getGroup(@PathVariable Long id) {
        Optional<Group> group = groupRepository.findById(id);
        return group.map(response -> ResponseEntity.ok().body(response)).orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
    }

    @PostMapping("/group")
    ResponseEntity<Group> createGroup(@Valid @RequestBody Group group) throws URISyntaxException {
        log.info("Request to create group: {}", group);
        Group result = groupRepository.save(group);
        return ResponseEntity.created(new URI("/api/group/" + result.getId())).body(result);
    }

    @PutMapping("/group/{id}")
    ResponseEntity<Group> updateGroup(@Valid @RequestBody Group group) {
        log.info("Request to update group: {}", group);
        Group result = groupRepository.save(group);
        return ResponseEntity.ok().body(result);
    }

    @DeleteMapping("/group/{id}")
    public ResponseEntity<?> deleteGroup(@PathVariable Long id) {
        log.info("Request to delete group: {}", id);
        groupRepository.deleteById(id);
        return ResponseEntity.ok().build();
    }
}

Restart the app, hit http://localhost:8080/api/groups with HTTPie, and you should see the list of groups.

http :8080/api/groups

You can create, read, update, and delete groups with the following commands.

http POST :8080/api/group name='Toronto JUG' city='Toronto' country=CA
http :8080/api/group/6
http PUT :8080/api/group/6 id=6 name='Toronto JUG' address='16 York St'
http DELETE :8080/api/group/6

Create an Angular App with the Angular CLI

The Angular CLI was a revolutionary tool when it was released in 2016. It's now the standard way to create new Angular projects and the easiest way to get started with Angular. Many web frameworks have adopted similar tools to improve their developer experience.

You don't have to install Angular CLI globally. The npx command can install and run it for you.

npx @angular/cli@17 new app --routing --style css --ssr false

Of course, you can use the tried-and-true npm i -g @angular/cli and ng new app --routing --style css --ssr false if you prefer. You can even remove the version number if you want to live on the edge.

After the app creation process completes, navigate into the app directory and install Angular Material to make the UI look beautiful, particularly on mobile devices.

cd app
ng add @angular/material

You'll be prompted to choose a theme, set up typography styles, and include animations. Select the defaults.

Modify app/src/app/app.component.html and move the CSS at the top to app.component.css.

Call your Spring Boot API and display the results

Update app.component.ts to fetch the list of groups when it loads.

import { Component, OnInit } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { HttpClient, HttpClientModule } from '@angular/common/http';
import { Group } from './model/group';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet, HttpClientModule],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css'
})
export class AppComponent implements OnInit {
  title = 'JUG Tours';
  loading = true;
  groups: Group[] = [];

  constructor(private http: HttpClient) {
  }

  ngOnInit() {
    this.loading = true;
    this.http.get<Group[]>('api/groups').subscribe((data: Group[]) => {
      this.groups = data;
      this.loading = false;
    });
  }
}

Before this compiles, you'll need to create a app/src/app/model/group.ts file with the following contents:

export class Group {
  id: number | null;
  name: string;

  constructor(group: Partial<Group> = {}) {
    this.id = group?.id || null;
    this.name = group?.name || '';
  }
}

Then, modify the app.component.html file to display the list of groups.

<main class="main">
  <div class="content">
    <div class="left-side">
      <h1>{{title}}</h1>
    </div>
    <div class="divider" role="separator" aria-label="Divider"></div>
    <div class="right-side">
      <div class="pill-group">
        @if (loading) {
        <p>Loading...</p>
        }
        @for (group of groups; track group) {
        <span class="pill">{{group.name}}</span>
        }
      </div>
    </div>
  </div>
</main>
<router-outlet></router-outlet>

Create a file called proxy.conf.js in the src folder of your Angular project and use it to define your proxies:

const PROXY_CONFIG = [
  {
    context: ['/api'],
    target: 'http://localhost:8080',
    secure: true,
    logLevel: 'debug'
  }
]

module.exports = PROXY_CONFIG;

Update angular.json and its serve command to use the proxy.

"serve": {
  "builder": "@angular-devkit/build-angular:dev-server",
  "configurations": {
    "production": {
      "buildTarget": "app:build:production"
    },
    "development": {
      "buildTarget": "app:build:development",
      "proxyConfig": "src/proxy.conf.js"
    }
  },
  "defaultConfiguration": "development"
},

Stop your app with Ctrl+C and restart it with npm start. Now you should see a list of groups in your Angular app!

Build an Angular `GroupList` component

Angular is a component framework that allows you to separate concerns easily. You don't want to render everything in your main AppComponent, so create a new component to display the list of groups.

ng g c group-list

This command will create a new component in src/app/group-list with a TypeScript file, HTML template, CSS file, and a test file. Standalone components are created by default in Angular 17. They allow you to isolate components to be self-contained and, therefore, easier to distribute.

Replace the code in group-list.component.ts with the following:

import { Component } from '@angular/core';
import { Group } from '../model/group';
import { HttpClient, HttpClientModule } from '@angular/common/http';
import { RouterLink } from '@angular/router';
import { MatButtonModule } from '@angular/material/button';
import { MatTableModule } from '@angular/material/table';
import { MatIconModule } from '@angular/material/icon';
import { DatePipe } from '@angular/common';

@Component({
  selector: 'app-group-list',
  standalone: true,
  imports: [RouterLink, MatButtonModule, MatTableModule, MatIconModule, DatePipe, HttpClientModule],
  templateUrl: './group-list.component.html',
  styleUrl: './group-list.component.css'
})
export class GroupListComponent {
  title = 'Group List';
  loading = true;
  groups: Group[] = [];
  displayedColumns = ['id', 'name', 'events', 'actions'];
  feedback: any = {};

  constructor(private http: HttpClient) {
  }

  ngOnInit() {
    this.loading = true;
    this.http.get<Group[]>('api/groups').subscribe((data: Group[]) => {
      this.groups = data;
      this.loading = false;
      this.feedback = {};
    });
  }

  delete(group: Group): void {
    if (confirm(`Are you sure you want to delete ${group.name}?`)) {
      this.http.delete(`api/group/${group.id}`).subscribe({
        next: () => {
          this.feedback = {type: 'success', message: 'Delete was successful!'};
          setTimeout(() => {
            this.ngOnInit();
          }, 1000);
        },
        error: () => {
          this.feedback = {type: 'warning', message: 'Error deleting.'};
        }
      });
    }
  }

  protected readonly event = event;
}

Update its HTML template to use Angular Material's table component.

<nav aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-item"><a routerLink="/">Home</a></li>
    <li class="breadcrumb-item active">Groups</li>
  </ol>
</nav>

<a [routerLink]="['/group/new']" mat-raised-button color="primary" style="float: right" id="add">Add Group</a>

<h2>{{title}}</h2>
@if (loading) {
<div>
  <p>Loading...</p>
</div>
} @else {
  @if (feedback.message) {
    <div class="alert alert-{{feedback.type}}">{{ feedback.message }}</div>
  }
  <table mat-table [dataSource]="groups">
    <ng-container matColumnDef="id">
      <mat-header-cell *matHeaderCellDef> ID </mat-header-cell>
      <mat-cell *matCellDef="let item"> {{ item.id }} </mat-cell>
    </ng-container>
    <ng-container matColumnDef="name">
      <mat-header-cell *matHeaderCellDef> Name </mat-header-cell>
      <mat-cell *matCellDef="let item"> {{ item.name }} </mat-cell>
    </ng-container>
    <ng-container matColumnDef="events">
      <mat-header-cell *matHeaderCellDef> Events </mat-header-cell>
      <mat-cell *matCellDef="let item">
        @for (event of item.events; track event) {
          {{event.date | date }}: {{ event.title }}
          <br/>
        }
      </mat-cell>
    </ng-container>
    <ng-container matColumnDef="actions">
      <mat-header-cell *matHeaderCellDef> Actions </mat-header-cell>
      <mat-cell *matCellDef="let item">
        <a [routerLink]="['../group', item.id ]" mat-raised-button color="accent">Edit</a>&nbsp;
        <button (click)="delete(item)" mat-button color="warn"><mat-icon>delete</mat-icon></button>
      </mat-cell>
    </ng-container>
    <mat-header-row *matHeaderRowDef="displayedColumns"></mat-header-row>
    <mat-row *matRowDef="let row; columns: displayedColumns;"></mat-row>
  </table>
}

Create a HomeComponent to display a welcome message and a link to the groups page. This component will be the default route for the app.

ng g c home

Update home.component.html with the following:

<a mat-button color="primary" href="/groups">Manage JUG Tour</a>

Add an import for MatButtonModule to home.component.ts:

import { MatButtonModule } from '@angular/material/button';

@Component({
  selector: 'app-home',
  standalone: true,
  imports: [MatButtonModule],
  ...
})

Change app.component.html to remove the list of groups above <router-outlet>:

<div class="content" role="main">
  <router-outlet></router-outlet>
</div>

And remove the groups fetching logic from app.component.ts:

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet],
  templateUrl: './app.component.html',
  styleUrl: './app.component.css'
})
export class AppComponent {
  title = 'JUG Tours';
}

Add a route for the HomeComponent and GroupListComponent to app.routes.ts:

import { Routes } from '@angular/router';
import { HomeComponent } from './home/home.component';
import { GroupListComponent } from './group-list/group-list.component';

export const routes: Routes = [
  { path: '', redirectTo: '/home', pathMatch: 'full' },
  {
    path: 'home',
    component: HomeComponent
  },
  {
    path: 'groups',
    component: GroupListComponent
  }
];

Update the CSS in styles.css to have rules for the breadcrumb and alert classes:

/* https://careydevelopment.us/blog/angular-how-to-add-breadcrumbs-to-your-ui */
ol.breadcrumb {
  padding: 0;
  list-style-type: none;
  margin: 5px 0 0 0;
}

.breadcrumb-item + .active {
  color: inherit;
  font-weight: 500;
}

.breadcrumb-item {
  color: #3F51B5;
  font-size: 1rem;
  text-decoration: underline;
  cursor: pointer;
}

.breadcrumb-item + .breadcrumb-item {
  padding-left: 0.5rem;
}

.breadcrumb-item + .breadcrumb-item::before {
  display: inline-block;
  padding-right: 0.5rem;
  color: rgb(108, 117, 125);
  content: "/";
}

ol.breadcrumb li {
  list-style-type: none;
}

ol.breadcrumb li {
  list-style-type: none;
  display: inline
}

.alert {
  padding: 0.75rem 1.25rem;
  margin-bottom: 1rem;
  border: 1px solid transparent;
}

.alert-success {
  color: #155724;
  background-color: #d4edda;
  border-color: #c3e6cb;
}

.alert-error {
  color: #721c24;
  background-color: #f8d7da;
  border-color: #f5c6cb;
}

Run npm start in your app directory to see how everything looks. Click on Manage JUG Tour, and you should see a list of the default groups.

To squish the Actions column to the right, add the following to group-list.component.css:

.mat-column-actions {
  flex: 0 0 120px;
}

Your Angular app should update itself as you make changes.

It's great to see your Spring Boot API's data in your Angular app, but it's no fun if you can't modify it!

Build an Angular `GroupEdit` component

Create a group-edit component and use Angular's HttpClient to fetch the group resource with the ID from the URL.

ng g c group-edit

Add a route for this component to app.routes.ts:

import { GroupEditComponent } from './group-edit/group-edit.component';

export const routes: Routes = [
  ...
  {
    path: 'group/:id',
    component: GroupEditComponent
  }
];

Replace the code in group-edit.component.ts with the following:

import { Component, OnInit } from '@angular/core';
import { ActivatedRoute, Router, RouterLink } from '@angular/router';
import { map, of, switchMap } from 'rxjs';
import { Group } from '../model/group';
import { Event } from '../model/event';
import { HttpClient, HttpClientModule } from '@angular/common/http';
import { MatInputModule } from '@angular/material/input';
import { FormsModule } from '@angular/forms';
import { MatButtonModule } from '@angular/material/button';
import { MatDatepickerModule } from '@angular/material/datepicker';
import { MatIconModule } from '@angular/material/icon';
import { MatNativeDateModule } from '@angular/material/core';
import { MatTooltipModule } from '@angular/material/tooltip';

@Component({
  selector: 'app-group-edit',
  standalone: true,
  imports: [
    FormsModule,
    HttpClientModule,
    MatInputModule,
    MatButtonModule,
    MatDatepickerModule,
    MatIconModule,
    MatNativeDateModule,
    MatTooltipModule,
    RouterLink
  ],
  templateUrl: './group-edit.component.html',
  styleUrl: './group-edit.component.css'
})
export class GroupEditComponent implements OnInit {
  group!: Group;
  feedback: any = {};

  constructor(private route: ActivatedRoute, private router: Router,
              private http: HttpClient) {
  }

  ngOnInit() {
    this.route.params.pipe(
      map(p => p['id']),
      switchMap(id => {
        if (id === 'new') {
          return of(new Group());
        }
        return this.http.get<Group>(`api/group/${id}`);
      })
    ).subscribe({
      next: group => {
        this.group = group;
        this.feedback = {};
      },
      error: () => {
        this.feedback = {type: 'warning', message: 'Error loading'};
      }
    });
  }

  save() {
    const id = this.group.id;
    const method = id ? 'put' : 'post';

    this.http[method](`/api/group${id ? '/' + id : ''}`, this.group).subscribe({
      next: () => {
        this.feedback = {type: 'success', message: 'Save was successful!'};
        setTimeout(async () => {
          await this.router.navigate(['/groups']);
        }, 1000);
      },
      error: () => {
        this.feedback = {type: 'error', message: 'Error saving'};
      }
    });
  }

  async cancel() {
    await this.router.navigate(['/groups']);
  }

  addEvent() {
    this.group.events.push(new Event());
  }

  removeEvent(index: number) {
    this.group.events.splice(index, 1);
  }
}

Create a model/event.ts file so this component will compile.

export class Event {
  id: number | null;
  date: Date | null;
  title: string;

  constructor(event: Partial<Event> = {}) {
    this.id = event?.id || null;
    this.date = event?.date || null;
    this.title = event?.title || '';
  }
}

Update model/group.ts to include the Event class.

import { Event } from './event';

export class Group {
  id: number | null;
  name: string;
  events: Event[];

  constructor(group: Partial<Group> = {}) {
    this.id = group?.id || null;
    this.name = group?.name || '';
    this.events = group?.events || [];
  }
}

The GroupEditComponent needs to render a form, so update group-edit.component.html with the following:

<nav aria-label="breadcrumb">
  <ol class="breadcrumb">
    <li class="breadcrumb-item"><a routerLink="/">Home</a></li>
    <li class="breadcrumb-item"><a routerLink="/groups">Groups</a></li>
    <li class="breadcrumb-item active">Edit Group</li>
  </ol>
</nav>

<h2>Group Information</h2>
@if (feedback.message) {
<div class="alert alert-{{feedback.type}}">{{ feedback.message }}</div>
}
@if (group) {
<form #editForm="ngForm" (ngSubmit)="save()">
  @if (group.id) {
  <mat-form-field class="full-width">
    <mat-label>ID</mat-label>
    <input matInput [(ngModel)]="group.id" id="id" name="id" placeholder="ID" readonly>
  </mat-form-field>
  }
  <mat-form-field class="full-width">
    <mat-label>Name</mat-label>
    <input matInput [(ngModel)]="group.name" id="name" name="name" placeholder="Name" required>
  </mat-form-field>
  @if (group.events.length) {
  <h3>Events</h3>
  }
  @for (event of group.events; track event; let i = $index) {
  <div class="full-width">
    <mat-form-field style="width: 35%">
      <mat-label>Date</mat-label>
      <input matInput [matDatepicker]="picker"
             [(ngModel)]="group.events[i].date" name="group.events[{{i}}].date" placeholder="Date">
      <mat-datepicker-toggle matSuffix [for]="picker"></mat-datepicker-toggle>
      <mat-datepicker #picker></mat-datepicker>
    </mat-form-field>
    <mat-form-field style="width: 65%">
      <mat-label>Title</mat-label>
      <input matInput [(ngModel)]="group.events[i].title" name="group.events[{{i}}].title" placeholder="Title">
    </mat-form-field>
    <button mat-icon-button (click)="removeEvent(i)" aria-label="Remove Event"
            style="float: right; margin: -70px -5px 0 0">
      <mat-icon>delete</mat-icon>
    </button>
  </div>
  }
  <div class="button-row" role="group">
    @if (group.id) {
    <button type="button" mat-mini-fab color="accent" (click)="addEvent()"
            aria-label="Add Event" matTooltip="Add Event"
            style="float: right; margin-top: -4px">
      <mat-icon>add</mat-icon>
    </button>
    }
    <button type="submit" mat-raised-button color="primary" [disabled]="!editForm.form.valid" id="save">Save</button>
    <button type="button" mat-button color="accent" (click)="cancel()" id="cancel">Cancel</button>
  </div>
</form>
}

If you look closely, you'll notice this component allows you to edit events for a group. This component is an excellent example of how to handle nested objects in Angular.

Update group-edit.component.css to make things look better on all devices:

form, h2 {
  min-width: 150px;
  max-width: 700px;
  width: 100%;
  margin: 10px auto;
}

.alert {
  max-width: 660px;
  margin: 0 auto;
}

.full-width {
  width: 100%;
}

Now, with your Angular app running, you should be able to add and edit groups! Yaasss! 👏👏👏

To make the navbar at the top use Angular Material colors, add the following to the top of app.component.html:

<mat-toolbar role="banner" color="primary">
  <svg id="angular-logo" height="35" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 960" fill="#fff">
    <g>
      <polygon points="562.6,109.8 804.1,629.5 829.2,233.1"/>
      <polygon points="624.9,655.9 334.3,655.9 297.2,745.8 479.6,849.8 662,745.8"/>
      <polygon points="384.1,539.3 575.2,539.3 479.6,307"/>
      <polygon points="396.6,109.8 130,233.1 155.1,629.5"/>
    </g>
  </svg>
  <span>{{ title }}</span>
  <div class="spacer"></div>
  <a aria-label="OktaDev on Twitter" target="_blank" rel="noopener" href="https://twitter.com/oktadev" title="Twitter">
    <svg id="twitter-logo" height="35" data-name="Logo" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 400">
      <rect width="400" height="400" fill="none"/>
      <path
        d="M153.62,301.59c94.34,0,145.94-78.16,145.94-145.94,0-2.22,0-4.43-.15-6.63A104.36,104.36,0,0,0,325,122.47a102.38,102.38,0,0,1-29.46,8.07,51.47,51.47,0,0,0,22.55-28.37,102.79,102.79,0,0,1-32.57,12.45,51.34,51.34,0,0,0-87.41,46.78A145.62,145.62,0,0,1,92.4,107.81a51.33,51.33,0,0,0,15.88,68.47A50.91,50.91,0,0,1,85,169.86c0,.21,0,.43,0,.65a51.31,51.31,0,0,0,41.15,50.28,51.21,51.21,0,0,1-23.16.88,51.35,51.35,0,0,0,47.92,35.62,102.92,102.92,0,0,1-63.7,22A104.41,104.41,0,0,1,75,278.55a145.21,145.21,0,0,0,78.62,23"
        fill="#fff"/>
    </svg>
  </a>
  <a aria-label="OktaDev on YouTube" target="_blank" rel="noopener" href="https://youtube.com/oktadev" title="YouTube">
    <svg id="youtube-logo" height="35" data-name="Logo" xmlns="http://www.w3.org/2000/svg"
         viewBox="0 0 24 24" fill="#fff">
      <path d="M0 0h24v24H0V0z" fill="none"/>
      <path
        d="M21.58 7.19c-.23-.86-.91-1.54-1.77-1.77C18.25 5 12 5 12 5s-6.25 0-7.81.42c-.86.23-1.54.91-1.77 1.77C2 8.75 2 12 2 12s0 3.25.42 4.81c.23.86.91 1.54 1.77 1.77C5.75 19 12 19 12 19s6.25 0 7.81-.42c.86-.23 1.54-.91 1.77-1.77C22 15.25 22 12 22 12s0-3.25-.42-4.81zM10 15V9l5.2 3-5.2 3z"/>
    </svg>
  </a>
</mat-toolbar>

Since this is not a standalone component, you must import MatToolbarModule in app.component.ts.

import { MatToolbarModule } from '@angular/material/toolbar';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet, MatToolbarModule],
  ...
})

Make some adjustments in app.component.css to make the toolbar look nicer.

Change the margin for .social-links to .5rem and remove the rules for .social-links path and .social-links a:hover below it.
Add a .spacer rule with flex: 1 1 auto in its properties.
Change the .content rule to be as follows:

.content {
  display: flex;
  margin: 10px auto;
  padding: 0 16px;
  max-width: 960px;
  flex-direction: column;
  align-items: stretch;
}

Now the app fills the screen more, and the toolbar has matching colors.

Secure Spring Boot with OpenID Connect and OAuth

I love building simple CRUD apps to learn a new tech stack, but I think it's even cooler to build a secure one. So let's do that!

Spring Security added support for OpenID Connect (OIDC) in version 5.0, circa 2017. This is awesome because it means you can use Spring Security to secure your app with a third-party identity provider (IdP) like Auth0. This is a much better option than trying to build your own authentication system and store user credentials.

Add the Okta Spring Boot starter to do OIDC authentication in your pom.xml. This will also add Spring Security to your app.

<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-boot-starter</artifactId>
    <version>3.0.6</version>
</dependency>

Install the Auth0 CLI (if you haven't already) and run auth0 login in a shell.

Next, run auth0 apps create to register a new OIDC app with appropriate callbacks:

auth0 apps create \
  --name "Bootiful Angular" \
  --description "Spring Boot + Angular = ❤️" \
  --type regular \
  --callbacks http://localhost:8080/login/oauth2/code/okta,http://localhost:4200/login/oauth2/code/okta \
  --logout-urls http://localhost:8080,http://localhost:4200 \
  --reveal-secrets

Copy the returned values from this command into an .okta.env file:

export OKTA_OAUTH2_ISSUER=https://<your-auth0-domain>/
export OKTA_OAUTH2_CLIENT_ID=<your-client-id>
export OKTA_OAUTH2_CLIENT_SECRET=<your-client-secret>

If you're on Windows, use set instead of export to set these environment variables and name the file .okta.env.bat:

set OKTA_OAUTH2_ISSUER=https://<your-auth0-domain>/
set OKTA_OAUTH2_CLIENT_ID=<your-client-id>
set OKTA_OAUTH2_CLIENT_SECRET=<your-client-secret>

Add *.env to your .gitignore file so you don't accidentally expose your client secret.

Then, run source .okta.env (or .okta.env.bat on Windows) to set these environment variables in your current shell.

Finally, run ./mvnw (or mvnw on Windows) to start the app.

source .okta.env
./mvnw spring-boot:run

You can then open http://localhost:8080 in your favorite browser. You'll be redirected to authenticate and returned afterward. You'll see a 404 error from Spring Boot since you have nothing mapped to the default / route.

Configure Spring Security for maximum protection

To make Spring Security Angular-friendly, create a SecurityConfiguration.java file in src/main/java/.../jugtours/config. Create the config directory and put this class in it.

package com.okta.developer.jugtours.config;

import com.okta.developer.jugtours.web.CookieCsrfFilter;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.www.BasicAuthenticationFilter;
import org.springframework.security.web.csrf.CookieCsrfTokenRepository;
import org.springframework.security.web.csrf.CsrfTokenRequestAttributeHandler;

import static org.springframework.security.config.Customizer.withDefaults;

@Configuration
public class SecurityConfiguration {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests((authz) -> authz
                .requestMatchers("/", "/index.html", "*.ico", "*.css", "*.js", "/api/user").permitAll()
                .anyRequest().authenticated())
            .oauth2Login(withDefaults())
            .oauth2ResourceServer((oauth2) -> oauth2.jwt(withDefaults()))
            .csrf((csrf) -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler()))
            .addFilterAfter(new CookieCsrfFilter(), BasicAuthenticationFilter.class);

        return http.build();
    }
}

This class has a lot going on, so let me explain a few things. In previous versions of Spring Security, there was an authorizeRequests() lambda you could use to secure paths. Since Spring Security 3.1, it's deprecated, and you should use authorizeHttpRequests(). The authorizeRequests() lambda is permissive by default, which means any paths you don't specify will be allowed. The recommended way, shown here with authorizeHttpRequests(), denies by default. This means you have to specify the resources you want to allow Spring Security to serve up, as well as the ones that the Angular app has.

The requestMatchers line defines the URLs allowed for anonymous users. You will soon configure things so your Spring Boot app serves up your Angular app, hence the reason for allowing /, /index.html, and web files. You might also notice an exposed /api/user path.

Configuring CSRF (cross-site request forgery) protection with CookieCsrfTokenRepository.withHttpOnlyFalse() means that the XSRF-TOKEN cookie won't be marked HTTP-only, so Angular can read it and send it back when it tries to manipulate data. The CsrfTokenRequestAttributeHandler is no longer the default, so you have to configure it as the request handler. To learn more, you can read this Stack Overflow answer. Basically, since we're not sending the CSRF token to an HTML page, we don't have to worry about BREACH attacks. This means we can revert to the previous default from Spring Security 5.

You'll need to create the CookieCsrfFilter class that's added because Spring Security 6 no longer sets the cookie for you. Create it in the web package.

package com.okta.developer.jugtours.web;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.web.csrf.CsrfToken;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

/**
 * Spring Security 6 doesn't set an XSRF-TOKEN cookie by default.
 * This solution is
 * <a href="https://github.com/spring-projects/spring-security/issues/12141#issuecomment-1321345077">
 * recommended by Spring Security.</a>
 */
public class CookieCsrfFilter extends OncePerRequestFilter {

    /**
     * {@inheritDoc}
     */
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        CsrfToken csrfToken = (CsrfToken) request.getAttribute(CsrfToken.class.getName());
        response.setHeader(csrfToken.getHeaderName(), csrfToken.getToken());
        filterChain.doFilter(request, response);
    }
}

Create src/main/java/.../jugtours/web/UserController.java and populate it with the following code. Angular will use this API to 1) find out if a user is authenticated and 2) perform global logout.

package com.okta.developer.jugtours.web;

import jakarta.servlet.http.HttpServletRequest;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.client.registration.ClientRegistration;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import java.text.MessageFormat;

import static java.util.Map.of;

@RestController
public class UserController {
    private final ClientRegistration registration;

    public UserController(ClientRegistrationRepository registrations) {
        this.registration = registrations.findByRegistrationId("okta");
    }

    @GetMapping("/api/user")
    public ResponseEntity<?> getUser(@AuthenticationPrincipal OAuth2User user) {
        if (user == null) {
            return new ResponseEntity<>("", HttpStatus.OK);
        } else {
            return ResponseEntity.ok().body(user.getAttributes());
        }
    }

    @PostMapping("/api/logout")
    public ResponseEntity<?> logout(HttpServletRequest request) {
        // send logout URL to client so they can initiate logout
        var issuerUri = registration.getProviderDetails().getIssuerUri();
        var originUrl = request.getHeader(HttpHeaders.ORIGIN);
        Object[] params = {issuerUri, registration.getClientId(), originUrl};
        // Yes! We @ Auth0 should have an end_session_endpoint in our OIDC metadata.
        // It's not included at the time of this writing, but will be coming soon!
        var logoutUrl = MessageFormat.format("{0}v2/logout?client_id={1}&returnTo={2}", params);
        request.getSession().invalidate();
        return ResponseEntity.ok().body(of("logoutUrl", logoutUrl));
    }
}

You'll also want to add user information when creating groups so that you can filter by your JUG tour. Add a UserRepository.java in the same directory as GroupRepository.java.

package com.okta.developer.jugtours.model;

import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, String> {
}

Add a new findAllByUserId(String id) method to GroupRepository.java.

List<Group> findAllByUserId(String id);

Then inject UserRepository into GroupController.java and use it to create (or grab an existing user) when adding a new group. While you're there, modify the groups() method to filter by user.

package com.okta.developer.jugtours.web;

import com.okta.developer.jugtours.model.Group;
import com.okta.developer.jugtours.model.GroupRepository;
import com.okta.developer.jugtours.model.User;
import com.okta.developer.jugtours.model.UserRepository;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.web.bind.annotation.*;

import jakarta.validation.Valid;
import java.net.URI;
import java.net.URISyntaxException;
import java.security.Principal;
import java.util.Collection;
import java.util.Map;
import java.util.Optional;

@RestController
@RequestMapping("/api")
class GroupController {

    private final Logger log = LoggerFactory.getLogger(GroupController.class);
    private final GroupRepository groupRepository;
    private final UserRepository userRepository;

    public GroupController(GroupRepository groupRepository, UserRepository userRepository) {
        this.groupRepository = groupRepository;
        this.userRepository = userRepository;
    }

    @GetMapping("/groups")
    Collection<Group> groups(Principal principal) {
        return groupRepository.findAllByUserId(principal.getName());
    }

    @GetMapping("/group/{id}")
    ResponseEntity<?> getGroup(@PathVariable Long id) {
        Optional<Group> group = groupRepository.findById(id);
        return group.map(response -> ResponseEntity.ok().body(response))
            .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
    }

    @PostMapping("/group")
    ResponseEntity<Group> createGroup(@Valid @RequestBody Group group,
                                      @AuthenticationPrincipal OAuth2User principal) throws URISyntaxException {
        log.info("Request to create group: {}", group);
        Map<String, Object> details = principal.getAttributes();
        String userId = details.get("sub").toString();

        // check to see if user already exists
        Optional<User> user = userRepository.findById(userId);
        group.setUser(user.orElse(new User(userId,
            details.get("name").toString(), details.get("email").toString())));

        Group result = groupRepository.save(group);
        return ResponseEntity.created(new URI("/api/group/" + result.getId()))
            .body(result);
    }

    @PutMapping("/group/{id}")
    ResponseEntity<Group> updateGroup(@Valid @RequestBody Group group) {
        log.info("Request to update group: {}", group);
        Group result = groupRepository.save(group);
        return ResponseEntity.ok().body(result);
    }

    @DeleteMapping("/group/{id}")
    public ResponseEntity<?> deleteGroup(@PathVariable Long id) {
        log.info("Request to delete group: {}", id);
        groupRepository.deleteById(id);
        return ResponseEntity.ok().build();
    }
}

To highlight the changes, please review the groups() and createGroup() methods above. I think it's pretty slick that Spring JPA will create the findAllByUserId() method/query for you.

Update Angular to handle CSRF and be identity-aware

I like Angular because it's a secure-first framework. It has built-in support for CSRF, and it's easy to make it identity-aware. Let's do both!

Angular's HttpClient supports the client-side half of the CSRF protection. It'll read the cookie sent by Spring Boot and return it in an X-XSRF-TOKEN header. You can read more about this at Angular's Security docs.

Update your Angular app's authentication mechanism

Create a new AuthService class to communicate with your Spring Boot API for authentication information. Add the following code to a new file at app/src/app/auth.service.ts.

import { Injectable } from '@angular/core';
import { Location } from '@angular/common';
import { BehaviorSubject, lastValueFrom, Observable } from 'rxjs';
import { HttpClient, HttpHeaders } from '@angular/common/http';
import { map } from 'rxjs/operators';
import { User } from './model/user';

const headers = new HttpHeaders().set('Accept', 'application/json');

@Injectable({
  providedIn: 'root'
})
export class AuthService {
  $authenticationState = new BehaviorSubject<boolean>(false);

  constructor(private http: HttpClient, private location: Location) {
  }

  getUser(): Observable<User> {
    return this.http.get<User>('/api/user', {headers}, )
      .pipe(map((response: User) => {
          if (response !== null) {
            this.$authenticationState.next(true);
          }
          return response;
        })
      );
  }

  async isAuthenticated(): Promise<boolean> {
    const user = await lastValueFrom(this.getUser());
    return user !== null;
  }

  login(): void {
    location.href = `${location.origin}${this.location.prepareExternalUrl('oauth2/authorization/okta')}`;
  }

  logout(): void {
    this.http.post('/api/logout', {}, { withCredentials: true }).subscribe((response: any) => {
      location.href = response.logoutUrl;
    });
  }
}

Add the referenced User class to app/src/app/model/user.ts.

export class User {
  email!: number;
  name!: string;
}

AuthService depends on HttpClient, so you must update app.config.ts to import and use provideHttpClient.

import { provideHttpClient } from '@angular/common/http';

export const appConfig: ApplicationConfig = {
   providers: [provideRouter(routes), provideAnimations(), provideHttpClient()]
};

Modify home.component.ts to use AuthService to see if the user is logged in.

import { Component, OnInit } from '@angular/core';
import { MatButtonModule } from '@angular/material/button';
import { RouterLink } from '@angular/router';
import { User } from '../model/user';
import { AuthService } from '../auth.service';

@Component({
  selector: 'app-home',
  standalone: true,
  imports: [MatButtonModule, RouterLink],
  templateUrl: './home.component.html',
  styleUrl: './home.component.css'
})
export class HomeComponent implements OnInit {
  isAuthenticated!: boolean;
  user!: User;

  constructor(public auth: AuthService) {
  }

  async ngOnInit() {
    this.isAuthenticated = await this.auth.isAuthenticated();
    this.auth.getUser().subscribe(data => this.user = data);
  }
}

Modify home.component.html to show the Login button if the user is not logged in. Otherwise, show a Logout button.

@if (user) {
  <h2>Welcome, {{user.name}}!</h2>
  <a mat-button color="primary" routerLink="/groups">Manage JUG Tour</a>
  <br/><br/>
  <button mat-raised-button color="primary" (click)="auth.logout()" id="logout">Logout</button>
} @else {
  <p>Please log in to manage your JUG Tour.</p>
  <button mat-raised-button color="primary" (click)="auth.login()" id="login">Login</button>
}

Update app/src/proxy.conf.js to have additional proxy paths for /oauth2 and /login.

const PROXY_CONFIG = [
  {
    context: ['/api', '/oauth2', '/login'],
    ...
  }
]

After all these changes, you should be able to restart both Spring Boot and Angular and witness the glory of securely planning your very own JUG Tour!

Configure Maven to Package Angular with Spring Boot

To build and package your Angular app with Maven, you can use the frontend-maven-plugin and Maven's profiles to activate it. Add properties for versions and a <profiles> section to your pom.xml.

<properties>
    ...
    <frontend-maven-plugin.version>1.15.0</frontend-maven-plugin.version>
    <node.version>v18.18.2</node.version>
    <npm.version>9.8.1</npm.version>
</properties>

... 

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <spring.profiles.active>dev</spring.profiles.active>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <build>
            <plugins>
                <plugin>
                    <artifactId>maven-resources-plugin</artifactId>
                    <executions>
                        <execution>
                            <id>copy-resources</id>
                            <phase>process-classes</phase>
                            <goals>
                                <goal>copy-resources</goal>
                            </goals>
                            <configuration>
                                <outputDirectory>${basedir}/target/classes/static</outputDirectory>
                                <resources>
                                    <resource>
                                        <directory>app/dist/app/browser</directory>
                                    </resource>
                                </resources>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
                <plugin>
                    <groupId>com.github.eirslett</groupId>
                    <artifactId>frontend-maven-plugin</artifactId>
                    <version>${frontend-maven-plugin.version}</version>
                    <configuration>
                        <workingDirectory>app</workingDirectory>
                    </configuration>
                    <executions>
                        <execution>
                            <id>install node</id>
                            <goals>
                                <goal>install-node-and-npm</goal>
                            </goals>
                            <configuration>
                                <nodeVersion>${node.version}</nodeVersion>
                                <npmVersion>${npm.version}</npmVersion>
                            </configuration>
                        </execution>
                        <execution>
                            <id>npm install</id>
                            <goals>
                                <goal>npm</goal>
                            </goals>
                            <phase>generate-resources</phase>
                        </execution>
                        <execution>
                            <id>npm test</id>
                            <goals>
                                <goal>npm</goal>
                            </goals>
                            <phase>test</phase>
                            <configuration>
                                <arguments>test -- --watch=false</arguments>
                            </configuration>
                        </execution>
                        <execution>
                            <id>npm build</id>
                            <goals>
                                <goal>npm</goal>
                            </goals>
                            <phase>compile</phase>
                            <configuration>
                                <arguments>run build</arguments>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
        <properties>
            <spring.profiles.active>prod</spring.profiles.active>
        </properties>
    </profile>
</profiles>

While you're at it, add the active profile setting to src/main/resources/application.properties:

spring.profiles.active=@spring.profiles.active@

After adding this, you should be able to run mvn spring-boot:run -Pprod and see your app running at http://localhost:8080.

If you start at the root, everything will work fine since Angular will handle routing. However, if you refresh the page when you're at http://localhost:8080/groups, you'll get a 404 error since Spring Boot doesn't have a route for /groups. To fix this, add a SpaWebFilter that conditionally forwards to the Angular app.

package com.okta.developer.jugtours.web;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

public class SpaWebFilter extends OncePerRequestFilter {

    /**
     * Forwards any unmapped paths (except those containing a period) to the client {@code index.html}.
     */
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, 
                                    FilterChain filterChain) throws ServletException, IOException {
        String path = request.getRequestURI();
        if (!path.startsWith("/api") &&
            !path.startsWith("/login") &&
            !path.startsWith("/oauth2") &&
            !path.contains(".") &&
            path.matches("/(.*)")) {
            request.getRequestDispatcher("/index.html").forward(request, response);
            return;
        }

        filterChain.doFilter(request, response);
    }
}

And add to your SecurityConfiguration.java class:

.addFilterAfter(new SpaWebFilter(), BasicAuthenticationFilter.class);

Now, if you restart, login, and navigate to /groups, refreshing will work as expected. 🤩

Verify Everything Works with Cypress

In this section, you'll learn how to integrate Cypress into this project to support end-to-end tests. Open a terminal, navigate to the app directory, and add the Cypress Angular Schematic:

ng add @cypress/schematic

Select the default answers when prompted. Then, update app/cypress/support/commands.ts to add a login(username, password) method:

/* eslint-disable @typescript-eslint/no-namespace */
/* eslint-disable @typescript-eslint/no-use-before-define */
// eslint-disable-next-line spaced-comment
/// <reference types="cypress" />

Cypress.Commands.add('login', (username: string, password: string) => {
  Cypress.log({
    message: [`🔐 Authenticating: ${username}`],
    autoEnd: false,
  })
  cy.origin(Cypress.env('E2E_DOMAIN'), {args: {username, password}},
    ({username, password}) => {
      cy.get('input[name=username]').type(username);
      cy.get('input[name=password]').type(`${password}{enter}`, {log: false});
    }
  );
});

declare global {
  namespace Cypress {
    interface Chainable {
      login(username: string, password: string): Cypress.Chainable;
    }
  }
}

// Convert this to a module instead of script (allows import/export)
export {};

Update app/cypress/support/e2e.ts to log in before each test and log out after.

import './commands';

beforeEach(() => {
  if (Cypress.env('E2E_USERNAME') === undefined) {
    console.error('E2E_USERNAME is not defined');
    alert('E2E_USERNAME is not defined');
    return;
  }
  cy.visit('/')
  cy.get('#login').click()
  cy.login(
    Cypress.env('E2E_USERNAME'),
    Cypress.env('E2E_PASSWORD')
  )
})

afterEach(() => {
  cy.visit('/')
  cy.get('#logout').click()
})

Rename app/cypress/e2e/spec.cy.ts to home.cy.ts and use it to verify that the home page loads.

describe('Home', () => {
  beforeEach(() => {
    cy.visit('/')
  });

  it('Visits the initial app page', () => {
    cy.contains('JUG Tours')
    cy.contains('Logout')
  })
})

Create a groups.cy.ts in the same directory to test CRUD on groups.

describe('Groups', () => {

  beforeEach(() => {
    cy.visit('/groups')
  });

  it('add button should exist', () => {
    cy.get('#add').should('exist');
  });

  it('should add a new group', () => {
    cy.get('#add').click();
    cy.get('#name').type('Test Group');
    cy.get('#save').click();
    cy.get('.alert-success').should('exist');
  });

  it('should edit a group', () => {
    cy.get('a').last().click();
    cy.get('#name').should('have.value', 'Test Group');
    cy.get('#cancel').click();
  });

  it('should delete a group', () => {
    cy.get('button').last().click();
    cy.on('window:confirm', () => true);
    cy.get('.alert-success').should('exist');
  });
});

Add environment variables with your credentials to the .okta.env (or .okta.env.bat) file you created earlier.

export CYPRESS_E2E_DOMAIN=<your-auth0-domain> # use the raw value, no https prefix
export CYPRESS_E2E_USERNAME=<your-email>
export CYPRESS_E2E_PASSWORD=<your-password>

Then, run source .okta.env (or .okta.env.bat on Windows) to set these environment variables and start the app.

mvn spring-boot:run -Pprod

In another terminal window, run the Cypress tests with Electron.

source .okta.env
cd app
npx cypress run --browser electron --config baseUrl=http://localhost:8080

Fix Unit Tests

If you run npm test, you'll see several failures. That's because the components have dependencies that aren't imported in the tests. Update home.component.spec.ts to import HttpClientTestingModule:

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { HttpClientTestingModule } from '@angular/common/http/testing';
import { HomeComponent } from './home.component';

describe('HomeComponent', () => {
  let component: HomeComponent;
  let fixture: ComponentFixture<HomeComponent>;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [HomeComponent, HttpClientTestingModule],
    }).compileComponents();

    fixture = TestBed.createComponent(HomeComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });
});

In app.component.spec.ts, import MatToolBarModule and look for JUG Tours in the page.

import { TestBed } from '@angular/core/testing';
import { MatToolbarModule } from '@angular/material/toolbar';
import { RouterTestingModule } from '@angular/router/testing';
import { AppComponent } from './app.component';

describe('AppComponent', () => {
  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [RouterTestingModule, MatToolbarModule],
    }).compileComponents();
  });

  it('should create the app', () => {
    const fixture = TestBed.createComponent(AppComponent);
    const app = fixture.componentInstance;
    expect(app).toBeTruthy();
  });

  it(`should have the 'JUG Tours' title`, () => {
    const fixture = TestBed.createComponent(AppComponent);
    const app = fixture.componentInstance;
    expect(app.title).toEqual('JUG Tours');
  });

  it('should render title', () => {
    const fixture = TestBed.createComponent(AppComponent);
    fixture.detectChanges();
    const compiled = fixture.nativeElement as HTMLElement;
    expect(compiled.querySelector('mat-toolbar > span')?.textContent).toContain('JUG Tours');
  });
});

Then, update both group component tests to import HttpClientTestingModule and RouterTestingModule.

import { HttpClientTestingModule } from '@angular/common/http/testing';
import { RouterTestingModule } from '@angular/router/testing';

describe('...', () => {
  ...

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      imports: [..., HttpClientTestingModule, RouterTestingModule]
    });
    ...
  });

  ...
});

Now, npm test should pass.

If you run mvn test without setting environment variables, your Java tests will fail too. To fix this, add a src/test/java/com/okta/developer/jugtours/TestSecurityConfiguration.java class to mock the OAuth provider.

package com.okta.developer.jugtours;

import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.context.annotation.Bean;
import org.springframework.security.oauth2.client.InMemoryOAuth2AuthorizedClientService;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
import org.springframework.security.oauth2.client.registration.ClientRegistration;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
import org.springframework.security.oauth2.client.registration.InMemoryClientRegistrationRepository;
import org.springframework.security.oauth2.core.AuthorizationGrantType;
import org.springframework.security.oauth2.core.ClientAuthenticationMethod;
import org.springframework.security.oauth2.jwt.JwtDecoder;

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

import static org.mockito.Mockito.mock;

/**
 * This class allows you to run unit and integration tests without an IdP.
 */
@TestConfiguration
public class TestSecurityConfiguration {

    @Bean
    ClientRegistration clientRegistration() {
        return clientRegistrationBuilder().build();
    }

    @Bean
    ClientRegistrationRepository clientRegistrationRepository(ClientRegistration clientRegistration) {
        return new InMemoryClientRegistrationRepository(clientRegistration);
    }

    private ClientRegistration.Builder clientRegistrationBuilder() {
        Map<String, Object> metadata = new HashMap<>();
        metadata.put("end_session_endpoint", "https://example.org/logout");

        return ClientRegistration.withRegistrationId("oidc")
            .issuerUri("{baseUrl}")
            .redirectUri("{baseUrl}/{action}/oauth2/code/{registrationId}")
            .clientAuthenticationMethod(ClientAuthenticationMethod.CLIENT_SECRET_BASIC)
            .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
            .scope("read:user")
            .authorizationUri("https://example.org/login/oauth/authorize")
            .tokenUri("https://example.org/login/oauth/access_token")
            .jwkSetUri("https://example.org/oauth/jwk")
            .userInfoUri("https://api.example.org/user")
            .providerConfigurationMetadata(metadata)
            .userNameAttributeName("id")
            .clientName("Client Name")
            .clientId("client-id")
            .clientSecret("client-secret");
    }

    @Bean
    JwtDecoder jwtDecoder() {
        return mock(JwtDecoder.class);
    }

    @Bean
    OAuth2AuthorizedClientService authorizedClientService(ClientRegistrationRepository clientRegistrationRepository) {
        return new InMemoryOAuth2AuthorizedClientService(clientRegistrationRepository);
    }
}

Then, update JugToursApplicationTests.java in the same directory to use the new configuration.

@SpringBootTest(classes = {JugtoursApplication.class, TestSecurityConfiguration.class})

Run mvn test again, and your tests will pass. 🎉

Use GitHub Actions to Build and Test Your App

Add a GitHub workflow at .github/workflows/main.yml to prove that your tests run in CI.

name: JUG Tours CI

on: [push, pull_request]

jobs:
  build:
    name: Build and Test
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Java 17
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: 17
          cache: 'maven'
      - name: Run tests
        run: xvfb-run mvn verify -ntp -Pprod
      - name: Run e2e tests
        uses: cypress-io/github-action@v6
        with:
          browser: chrome
          start: mvn spring-boot:run -Pprod -ntp -f ../pom.xml
          install: false
          wait-on: http://localhost:8080
          wait-on-timeout: 120
          config: baseUrl=http://localhost:8080
          working-directory: app
        env:
          OKTA_OAUTH2_ISSUER: ${{ secrets.OKTA_OAUTH2_ISSUER }}
          OKTA_OAUTH2_CLIENT_ID: ${{ secrets.OKTA_OAUTH2_CLIENT_ID }}
          OKTA_OAUTH2_CLIENT_SECRET: ${{ secrets.OKTA_OAUTH2_CLIENT_SECRET }}
          CYPRESS_E2E_DOMAIN: ${{ secrets.CYPRESS_E2E_DOMAIN }}
          CYPRESS_E2E_USERNAME: ${{ secrets.CYPRESS_E2E_USERNAME }}
          CYPRESS_E2E_PASSWORD: ${{ secrets.CYPRESS_E2E_PASSWORD }}
      - name: Upload screenshots
        uses: actions/upload-artifact@v3
        if: failure()
        with:
          name: cypress-screenshots
          path: app/cypress/screenshots

You can see this workflow in action on GitHub, or you can try it yourself by creating a new GitHub repo and pushing your code to it.

Add environment variables for the above secrets to your GitHub repository at Settings > Secrets and variables > Actions > New Repository Secret.

Push your changes to GitHub and watch the CI workflow run. ✅

Build Something Fabulous with Spring Boot and Angular!

I hope this post has helped you learn how to build secure Angular and Spring Boot apps. Using OpenID Connect is a recommended practice for authenticating full-stack apps like this one, and Auth0 makes it easy to do. Adding CSRF protection and packaging your Spring Boot + Angular app as a single artifact is super cool too!

We've written some other fun Spring Boot, Angular, and JHipster tutorials. Check them out!

I've also written a couple of InfoQ mini-books that you might find useful:

The JHipster Mini-Book: Shows how I built 21-Points Health with JHipster (Angular, Spring Boot, Bootstrap, and more). It includes a chapter on microservices with Spring Boot, React, and Auth0.
The Angular Mini-Book: A practical guide to Angular, Bootstrap, and Spring Boot. It uses Kotlin and Gradle, recommended security practices, and contains several cloud deployment guides.

If you have any questions, please leave a comment below. If you want to see the completed code for this tutorial, check out its GitHub repo. Follow us on Twitter and YouTube for more content like this.

Micro Frontends for Java Microservices

Matt Raible — Fri, 20 Jan 2023 15:47:47 +0000

Microservices have been quite popular in the Java ecosystem ever since Spring Boot and Spring Cloud made them easy to build and deploy. Things have gotten even easier in recent years with the proliferation of new Java frameworks built specifically for microservices: MicroProfile, Micronaut, Quarkus, and Helidon. Not only do these frameworks provide an excellent developer experience, but they also tend to have built-in Docker support. They even work with GraalVM, so you can compile your apps to native code!

To be fair, MicroProfile isn't a framework; it's a spec with many implementations. In fact, both Quarkus and Helidon have MicroProfile flavors you can use.

Today, I'll show you how to build a Java microservices architecture that leverages micro frontends for the UI. The backend will use Spring Boot and Spring Cloud, while the frontend will use React. You can also use Angular or Vue if you'd like.

This tutorial is also available as a screencast.

NOTE: This video uses JHipster 7.9.3. All the steps will still work with JHipster 8.1.0, but you have to use Java 17 and Node 18.

Prerequisites:

You can install JHipster with npm:

npm i -g generator-jhipster@8

Java microservices with Spring Boot and JHipster

JHipster is an application generator that creates a Spring Boot backend. You can configure it to use SQL or NoSQL databases, plain ol' Spring MVC, or reactive with WebFlux. It also generates a UI for your REST API and offers you the choice of Angular, React, or Vue. Last year, I showed you how to build reactive Java microservices with Spring Boot and JHipster. In this tutorial, you'll build a gateway with Spring Cloud Gateway. Then, you create a blog microservice and a store microservice, each with its own database.

This microservices architecture had one major flaw: the UI for it is a monolith, with all its files on the gateway. This isn't good from a loose-coupling point of view because changes in a microservice might require changes in the UI. Instead of being able to deploy the microservice independently, you have to deploy the gateway too.

Today, I'm proud to show you how you can solve this problem with micro frontends. JHipster recently added support for micro-frontends. Microfrontends provide a way for you to remotely load and execute code at runtime so your microservice's UI can live in the same artifact without being coupled to the gateway!

In the previous paragraph, you might notice I spelled micro frontends three different ways. The current literature is all over the place on this one!

// Detect dark theme var iframe = document.getElementById('tweet-1499098253920460802-810'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1499098253920460802&theme=dark" }

I'm going to use "micro frontends" for the remainder of this post since that's what Cam Jackson used in his Micro Frontends article on Martin Fowler's blog.

A quick introduction to Module Federation

Webpack's Module Federation is one of the best-known implementations for micro frontends. Its ModuleFederationPlugin allows a build to provide or consume modules with other independent builds at runtime. It even allows you to share libraries between frontends to reduce the size of remote bundles.

Zack Jackson is the creator of Module Federation and recently collaborated with Manfred Steyer to create Native Federation. This means you can use micro frontend concepts with any build tool, not just webpack.

// Detect dark theme var iframe = document.getElementById('tweet-1564312149580582912-428'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1564312149580582912&theme=dark" }

Why should Java developers care?

I think micro frontends are a fascinating architectural concept. Microservices weave everything together on the backend with protocols like HTTP and gRPC. With micro frontends, it's all HTTP. You can see your app get stitched together by watching your browser's network console and seeing remote modules load.

I've encountered quite a few monolith UIs in my time as a consultant. The backend was a beautiful microservice architecture, but it was all tightly coupled on the frontend. There's a good chance many Java developers don't care about the UI because they just work on the beautiful backends. However, if you consider yourself a Java web developer, micro frontends are as revolutionary as HTML5!

And that's the beauty of this tutorial; you don't have to write any micro frontends. JHipster can create them for you!

Micro frontends in action with JHipster

I used a JDL (JHipster Domain Language) file named reactive-ms.jdl to create the reactive Java microservices tutorial I mentioned earlier. You can see this file online in the JDL samples repository.

I copied this file to reactive-mf.jdl and changed a few things for this tutorial:

Enabled micro frontends by adding microfrontends [blog, store] to the gateway's definition.
Changed the client framework from Vue to React.
Added clientFramework react and Cypress to each microservice.
Changed the service discovery to Consul, since this is the default in JHipster 8.
Added a deployment section for Kubernetes.

CAUTION: JHipster's JDL allows you to specify different client frameworks, but micro frontends will only work if you set the same one for all your apps.

Run the following command to create a new directory for your micro frontends project:

take micro-frontends-jhipster
# mkdir micro-frontends-jhipster && cd micro-frontends-jhipster if you don't have take installed

Download both the -ms and -mf JDLs and compare them in IntelliJ IDEA. You'll need IDEA's Command-line Launcher for the idea command to work.

jhipster download reactive-ms.jdl
jhipster download reactive-mf.jdl
idea diff reactive-ms.jdl reactive-mf.jdl

TIP: The JHipster JDL Plugin is a handy tool for working with JDL files.

Micro frontend options: Angular, React, and Vue

JHipster has support for the big three JavaScript frameworks: Angular, React, and Vue. All are implemented using TypeScript, and a newly generated app should have around 70% code coverage, both on the backend and frontend.

There is also a Svelte blueprint, but it does not support micro frontends at the time of this writing.

Build Java microservices with Spring Boot and WebFlux

To generate a microservices architecture with micro frontend support, run the following command:

jhipster jdl reactive-mf.jdl --monorepository --workspaces

The last two arguments are optional, but I expect you to use them for this tutorial. Without the monorepository flag, the gateway and microservices would have their own Git repos. The workspaces flag enables npm workspaces, which are kinda like having an aggregator pom.xml that allows you to execute commands across projects. It also makes it so there's only one node_modules in the root directory. To learn more, I recommend egghead's Introduction to Monorepos with NPM Workspaces.

If you want to use Angular, append --client-framework angular to the command above to override the JDL value:

--client-framework angular

If you'd rather try out Vue, use the following:

--client-framework vue

Run your reactive Spring Boot microservices

When the process is complete, cd into the gateway directory and start Consul, Keycloak, and PostgreSQL using Docker Compose.

cd gateway
docker compose -f src/main/docker/consul.yml up -d
docker compose -f src/main/docker/keycloak.yml up -d
docker compose -f src/main/docker/postgresql.yml up -d

Then, run ./gradlew (or npm run app:start if you prefer npm commands). When the startup process completes, open your favorite browser to http://localhost:8080, and log in with the credentials displayed on the page.

You'll be redirected back to the gateway, but the Entities menu won't have any links because the micro frontends it tries to load are unavailable.

Start the blog by opening a terminal and navigating to its directory. Then, start its database with Docker and the app with Gradle.

npm run docker:db:up
./gradlew

Open a new terminal and do the same for the store microservice.

You can verify everything is started using Consul at http://localhost:8500.

Refresh the gateway app; you should see menu items to navigate to the microservices now.

Zero turnaround development that sparks joy

At this point, I've only shown you how to run the Spring Boot backends with their packaged React apps. What if you want to work on the UI and have zero turnaround that sparks joy? ✨🤗

In the gateway app, run npm start. This command will run the UI on a web server, open a browser window to http://localhost:9000, and use Browsersync to keep your browser in sync with your code.

Modify the code in gateway/src/main/webapp/app/modules/home/home.tsx to make a quick change. For example, add the following HTML below the <h1>.

<h2 className="text-primary">
  Hi, I'm a quick edit!
</h2>

You'll see this change immediately appear within your browser.

Remove it, and it'll disappear right away too.

Now, open another terminal and navigate into the store directory. Run npm start, and you'll have a similar zero-turnaround experience when modifying files in the store app. The app will start a webserver on http://localhost:9002, and there will only be one menu item for product. Modify files in the store/src/main/webapp/app/entities/store/product directory, and you'll see the changes in your browser immediately. For example, change the wrapper <div> in product.tsx to have a background color:

<div className="bg-info">

The UI will change before you can Command+Tab back to your browser.

The backend has quick turnaround abilities too, thanks to Spring Boot devtools. If you modify a backend class, recompiling it will cause Spring Boot to reload your component lickety-split. It's pretty slick!

A look under the hood of micro frontends

When you're learning concepts like micro frontends, it's often helpful to look at the code that makes things work.

The gateway's webpack.microfrontend.js handles specifying the shared dependencies and components between apps. The src/main/webapp/app/shared/layout/menus/entities.tsx file contains the menu items for each micro frontend.

const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');

const packageJson = require('../package.json');
// Microfrontend api, should match across gateway and microservices.
const apiVersion = '0.0.1';

const sharedDefaults = { singleton: true, strictVersion: true, requiredVersion: apiVersion };
const shareMappings = (...mappings) => Object.fromEntries(mappings.map(map => [map, { ...sharedDefaults, version: apiVersion }]));

const shareDependencies = ({ skipList = [] } = {}) =>
  Object.fromEntries(
    Object.entries(packageJson.dependencies)
      .filter(([dependency]) => !skipList.includes(dependency))
      .map(([dependency, version]) => [dependency, { ...sharedDefaults, version, requiredVersion: version }]),
  );

module.exports = ({ serve }) => {
  return {
    optimization: {
      moduleIds: 'named',
      chunkIds: 'named',
      runtimeChunk: false,
    },

    plugins: [
      new ModuleFederationPlugin({
        shareScope: 'default',
        shared: {
          ...shareDependencies(),
          ...shareMappings(
            'app/config/constants',
            'app/config/store',
            'app/shared/error/error-boundary-routes',
            'app/shared/layout/menus/menu-components',
            'app/shared/layout/menus/menu-item',
            'app/shared/reducers',
            'app/shared/reducers/locale',
            'app/shared/reducers/reducer.utils',
            'app/shared/util/date-utils',
            'app/shared/util/entity-utils',
          ),
        },
      }),
    ],
    output: {
      publicPath: 'auto',
    },
  };
};

The blog's webpack.microfrontend.js looks similar, except that it exposes its remoteEntry.js, menu items, and routes.

const ModuleFederationPlugin = require('webpack/lib/container/ModuleFederationPlugin');
const { DefinePlugin } = require('webpack');

const packageJson = require('../package.json');
// Microfrontend api, should match across gateway and microservices.
const apiVersion = '0.0.1';

const sharedDefaults = { singleton: true, strictVersion: true, requiredVersion: apiVersion };
const shareMappings = (...mappings) => Object.fromEntries(mappings.map(map => [map, { ...sharedDefaults, version: apiVersion }]));

const shareDependencies = ({ skipList = [] } = {}) =>
  Object.fromEntries(
    Object.entries(packageJson.dependencies)
      .filter(([dependency]) => !skipList.includes(dependency))
      .map(([dependency, version]) => [dependency, { ...sharedDefaults, version, requiredVersion: version }]),
  );

module.exports = ({ serve }) => {
  return {
    optimization: {
      moduleIds: 'named',
      chunkIds: 'named',
      runtimeChunk: false,
    },

    plugins: [
      new ModuleFederationPlugin({
        name: 'blog',
        filename: 'remoteEntry.js',
        shareScope: 'default',
        exposes: {
          './entities-menu': './src/main/webapp/app/entities/menu',
          './entities-routes': './src/main/webapp/app/entities/routes',
        },
        shared: {
          ...shareDependencies(),
          ...shareMappings(
            'app/config/constants',
            'app/config/store',
            'app/shared/error/error-boundary-routes',
            'app/shared/layout/menus/menu-components',
            'app/shared/layout/menus/menu-item',
            'app/shared/reducers',
            'app/shared/reducers/locale',
            'app/shared/reducers/reducer.utils',
            'app/shared/util/date-utils',
            'app/shared/util/entity-utils',
          ),
        },
      }),
      new DefinePlugin({
        BLOG_I18N_RESOURCES_PREFIX: JSON.stringify(''),
      }),
    ],
    output: {
      publicPath: 'auto',
    },
  };
};

Build and run with Docker

To build Docker images for each application, run the following command from the root directory.

npm run java:docker

The command is slightly different if you're using a Mac with Apple Silicon.

npm run java:docker:arm64

TIP: You can see all npm scripts with npm run.

Then, navigate to the docker-compose directory, stop the existing containers, and start all the containers.

cd docker-compose
docker stop $(docker ps -a -q);
docker compose up

This command will start and run all the apps, their databases, Consul, and Keycloak. To make Keycloak work, you must add the following line to your hosts file (/etc/hosts on Mac/Linux, c:\Windows\System32\Drivers\etc\hosts on Windows).

127.0.0.1  keycloak

This is because you will access your application with a browser on your machine (where the name is localhost, or 127.0.0.1), but inside Docker it will run in its own container, where the name is keycloak.

If you want to prove everything works, ensure everything is started at http://localhost:8500, then run npm run e2e -ws from the root project directory. This command will run the Cypress tests that JHipster generates in your browser.

Switch identity providers

JHipster ships with Keycloak when you choose OAuth 2.0 / OIDC as the authentication type. However, you can easily change it to another identity provider, like Auth0!

First, you'll need to register a regular web application. Log in to your Auth0 account (or sign up if you don't have an account). You should have a unique domain like dev-xxx.us.auth0.com.

Select Create Application in the Applications section. Use a name like Micro Frontends, select Regular Web Applications, and click Create.

Switch to the Settings tab and configure your application settings:

Allowed Callback URLs: http://localhost:8080/login/oauth2/code/oidc
Allowed Logout URLs: http://localhost:8080/

Scroll to the bottom and click Save Changes.

In the roles section, create new roles named ROLE_ADMIN and ROLE_USER.

Create a new user account in the users section. Click the Role tab to assign the roles you just created to the new account.

Make sure your new user's email is verified before attempting to log in!

Next, head to Actions > Flows and select Login. Create a new action named Add Roles and use the default trigger and runtime. Change the onExecutePostLogin handler to be as follows:

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://www.jhipster.tech';
  if (event.authorization) {
    api.idToken.setCustomClaim('preferred_username', event.user.email);
    api.idToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
    api.accessToken.setCustomClaim(`${namespace}/roles`, event.authorization.roles);
  }
}

This code adds the user's roles to a custom claim (prefixed with https://www.jhipster.tech/roles). This claim is mapped to Spring Security authorities in SecurityUtils.java in the gateway app.

Select Deploy and drag the Add Roles action to your Login flow.

Edit docker-compose/central-server-config/application.yml and append the following YAML block to add your Auth0 settings.

jhipster:
  security:
    oauth2:
      audience: https://<your-auth0-domain>/api/v2/

spring:
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://<your-auth0-domain>/ # make sure to include the trailing slash!
        registration:
          oidc:
            client-id: <your-client-id>
            client-secret: <your-client-secret>

NOTE: Want to have all these steps automated for you? Vote for issue #351 in the Auth0 CLI project.

Stop all your Docker containers with Ctrl+C and start them again.

docker compose up

Now, Spring Security will be configured to use Auth0, and Consul will distribute these settings to all your microservices. When everything is started, navigate to http://localhost:8080 and click sign in. You will be prompted for your Auth0 credentials.

After entering your credentials, you'll be redirected back to the gateway, and your username will be displayed.

You should be able to add, edit, and delete blogs, posts, tags, and products, proving that your microservices and micro frontends can talk to each other.

If you'd like to use Okta for your identity provider, see JHipster's documentation.

TIP: You can configure JHipster quickly with the Okta CLI:

okta apps create jhipster

Deploy with Kubernetes

The JDL you used to generate this microservices stack has a section at the bottom for deploying to Kubernetes.

deployment {
  deploymentType kubernetes
  appsFolders [gateway, blog, store]
  clusteredDbApps [store]
  kubernetesNamespace demo
  kubernetesUseDynamicStorage true
  kubernetesStorageClassName ""
  serviceDiscoveryType consul
  dockerRepositoryName "mraible"
}

The jhipster jdl command generates a kubernetes directory with this information and configures all your apps, databases, and Consul to be Kubernetes-ready. If you have a Kubernetes cluster created, you can deploy to its demo namespace using the following command.

./kubectl-apply.sh -f

It also generates files for Kustomize and Skaffold if you'd prefer to use those tools. See the kubernetes/K8S-README.md file for more information.

I won't go into the nitty-gritty details of deploying a JHipster microservices stack to cloud providers with K8s, mainly because it's covered in previous blog posts. The first post below shows how to run Minikube locally, encrypt your secrets, and deploy to Google Cloud.

The JHipster team also has a blog you can follow at dev.to/jhipster.

Learn more about micro frontends and microservices

I hope you enjoyed this overview of how to use micro frontends within a Java microservices architecture. I like how micro frontends allow each microservice application to be self-contained and deployable, independent of the other microservices. It's also pretty neat how JHipster generates Docker and Kubernetes configuration for you. Cloud-native FTW!

You can find the source code for this example on GitHub, in the @oktadev/auth0-micro-frontends-jhipster-example repository.

If you'd like to learn more about micro frontends and microservices, I recommend these posts:

Please follow @auth0 and @oktadev on Twitter. We also have YouTube channels that you might enjoy at youtube.com/auth0 and youtube.com/oktadev. If you have any questions, please leave a comment below!

Use React and Spring Boot to Build a Simple CRUD App

Matt Raible — Wed, 18 Jan 2023 20:33:25 +0000

React was designed to make it painless to create interactive UIs. Its state management is efficient and only updates components when your data changes. Component logic is written in JavaScript, meaning you can keep state out of the DOM and create encapsulated components.

Developers like CRUD (create, read, update, and delete) apps because they show a lot of the base functionality you need when creating an app. Once you have the basics of CRUD completed in an app, most of the client-server plumbing is finished, and you can move on to implementing the necessary business logic.

Today, I'll show you how to create a basic CRUD app with Spring Boot and React. In this tutorial, I'll use the OAuth 2.0 Authorization Code flow and package the React app in the Spring Boot app for production. At the same time, I'll show you how to keep React's productive workflow for developing locally.

This tutorial is also available as a screencast.

You will need Java 17 and Node 16 installed to complete this tutorial.

Create an API app with Spring Boot

I'm a frequent speaker at conferences and user groups around the world. My favorite user groups to speak at are Java User Groups (JUGs). I've been a Java developer for almost 20 years and love the Java community. One of my good friends, James Ward, said doing a JUG Tour was one of his favorite developer advocate activities back in the day. I recently took his advice and traded overseas conferences for JUG meetups in the US.

Why am I telling you this? Because I thought it'd be fun to create a "JUG Tours" app today that allows you to create/edit/delete JUGs and view upcoming events.

To begin, navigate to start.spring.io and make the following selections:

Project: Maven Project
Group: com.okta.developer
Artifact: jugtours
Dependencies: JPA, H2, Web, Lombok

Click Generate Project, expand jugtours.zip after downloading, and open the project in your favorite IDE.

TIP: If you're using IntelliJ IDEA or Spring Tool Suite, you can also use Spring Initializr when creating a new project.

Add a JPA domain model

The first thing you'll need to do is to create a domain model that'll hold your data. At a high level, there's a Group that represents the JUG, an Event that has a many-to-one relationship with Group, and a User that has a one-to-many relationship with Group.

Create a src/main/java/com/okta/developer/jugtours/model directory and a Group.java class in it.

package com.okta.developer.jugtours.model;

import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.NonNull;
import lombok.RequiredArgsConstructor;

import jakarta.persistence.*;
import java.util.Set;

@Data
@NoArgsConstructor
@RequiredArgsConstructor
@Entity
@Table(name = "user_group")
public class Group {

    @Id
    @GeneratedValue
    private Long id;
    @NonNull
    private String name;
    private String address;
    private String city;
    private String stateOrProvince;
    private String country;
    private String postalCode;
    @ManyToOne(cascade=CascadeType.PERSIST)
    private User user;

    @OneToMany(fetch = FetchType.EAGER, cascade=CascadeType.ALL)
    private Set<Event> events;
}

Create an Event.java class in the same package.

package com.okta.developer.jugtours.model;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.Id;
import jakarta.persistence.ManyToMany;
import java.time.Instant;
import java.util.Set;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Builder
@Entity
public class Event {

    @Id
    @GeneratedValue
    private Long id;
    private Instant date;
    private String title;
    private String description;
    @ManyToMany
    private Set<User> attendees;
}

And a User.java class.

package com.okta.developer.jugtours.model;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import jakarta.persistence.Entity;
import jakarta.persistence.Id;
import jakarta.persistence.Table;

@Data
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "users")
public class User {

    @Id
    private String id;
    private String name;
    private String email;
}

Create a GroupRepository.java to manage the group entity.

package com.okta.developer.jugtours.model;

import org.springframework.data.jpa.repository.JpaRepository;

import java.util.List;

public interface GroupRepository extends JpaRepository<Group, Long> {
    Group findByName(String name);
}

To load some default data, create an Initializer.java class in the com.okta.developer.jugtours package.

package com.okta.developer.jugtours;

import com.okta.developer.jugtours.model.Event;
import com.okta.developer.jugtours.model.Group;
import com.okta.developer.jugtours.model.GroupRepository;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

import java.time.Instant;
import java.util.Collections;
import java.util.stream.Stream;

@Component
class Initializer implements CommandLineRunner {

    private final GroupRepository repository;

    public Initializer(GroupRepository repository) {
        this.repository = repository;
    }

    @Override
    public void run(String... strings) {
        Stream.of("Seattle JUG", "Denver JUG", "Dublin JUG",
                "London JUG").forEach(name ->
                repository.save(new Group(name))
        );

        Group djug = repository.findByName("Seattle JUG");
        Event e = Event.builder().title("Micro Frontends for Java Developers")
                .description("JHipster now has microfrontend support!")
                .date(Instant.parse("2022-09-13T17:00:00.000Z"))
                .build();
        djug.setEvents(Collections.singleton(e));
        repository.save(djug);

        repository.findAll().forEach(System.out::println);
    }
}

TIP: If your IDE has issues with Event.builder(), you need to turn on annotation processing and/or install the Lombok plugin. I had to uninstall/reinstall the Lombok plugin in IntelliJ IDEA to get things to work.

If you start your app (using ./mvnw spring-boot:run) it should result in something like:

Group(id=1, name=Seattle JUG, address=null, city=null, stateOrProvince=null, country=null, postalCode=null, user=null, 
  events=[Event(id=5, date=2022-09-13T17:00:00Z, title=Micro Frontends for Java Developers, description=JHipster now has microfrontend support!, attendees=[])])
Group(id=2, name=Denver JUG, address=null, city=null, stateOrProvince=null, country=null, postalCode=null, user=null, events=[])
Group(id=3, name=Dublin JUG, address=null, city=null, stateOrProvince=null, country=null, postalCode=null, user=null, events=[])
Group(id=4, name=London JUG, address=null, city=null, stateOrProvince=null, country=null, postalCode=null, user=null, events=[])

Add a GroupController.java class (in src/main/java/.../jugtours/web/GroupController.java) that allows you to CRUD groups.

package com.okta.developer.jugtours.web;

import com.okta.developer.jugtours.model.Group;
import com.okta.developer.jugtours.model.GroupRepository;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import jakarta.validation.Valid;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.Collection;
import java.util.Optional;

@RestController
@RequestMapping("/api")
class GroupController {

    private final Logger log = LoggerFactory.getLogger(GroupController.class);
    private GroupRepository groupRepository;

    public GroupController(GroupRepository groupRepository) {
        this.groupRepository = groupRepository;
    }

    @GetMapping("/groups")
    Collection<Group> groups() {
        return groupRepository.findAll();
    }

    @GetMapping("/group/{id}")
    ResponseEntity<?> getGroup(@PathVariable Long id) {
        Optional<Group> group = groupRepository.findById(id);
        return group.map(response -> ResponseEntity.ok().body(response))
                .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
    }

    @PostMapping("/group")
    ResponseEntity<Group> createGroup(@Valid @RequestBody Group group) throws URISyntaxException {
        log.info("Request to create group: {}", group);
        Group result = groupRepository.save(group);
        return ResponseEntity.created(new URI("/api/group/" + result.getId()))
                .body(result);
    }

    @PutMapping("/group/{id}")
    ResponseEntity<Group> updateGroup(@Valid @RequestBody Group group) {
        log.info("Request to update group: {}", group);
        Group result = groupRepository.save(group);
        return ResponseEntity.ok().body(result);
    }

    @DeleteMapping("/group/{id}")
    public ResponseEntity<?> deleteGroup(@PathVariable Long id) {
        log.info("Request to delete group: {}", id);
        groupRepository.deleteById(id);
        return ResponseEntity.ok().build();
    }
}

Add the following dependency to your pom.xml to fix compilation errors:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

If you stop and start your server app and hit http://localhost:8080/api/groups with your browser, or a command line client, you should see the list of groups.

You can create, read, update, and delete groups with the following HTTPie commands.

http POST :8080/api/group name='Utah JUG' city='Salt Lake City' country=USA
http :8080/api/group/6
http PUT :8080/api/group/6 id=6 name='Utah JUG' address='On the slopes'
http DELETE :8080/api/group/6

Create a React UI with Create React App

Create React App is a command line utility that generates React projects for you. It's a convenient tool because it also offers commands to build and optimize your project for production. It uses webpack under the covers to build everything.

Create a new project in the jugtours directory with npx.

npx create-react-app@5 app

After the app creation process completes, navigate into the app directory and install Bootstrap, cookie support for React, React Router, and Reactstrap.

cd app
npm i bootstrap@5 react-cookie@4 react-router-dom@6 reactstrap@9

You'll use Bootstrap's CSS and Reactstrap's components to make the UI look better, especially on mobile phones. If you'd like to learn more about Reactstrap, see reactstrap.github.io. It has extensive documentation on Reactstrap's various components and their use.

Add Bootstrap's CSS file as an import in app/src/index.js.

import 'bootstrap/dist/css/bootstrap.min.css';

Call your Spring Boot API and display the results

Modify app/src/App.js to use the following code that calls /api/groups and displays the list in the UI.

import React, { useEffect, useState } from 'react';
import logo from './logo.svg';
import './App.css';

const App = () => {

  const [groups, setGroups] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);

    fetch('api/groups')
      .then(response => response.json())
      .then(data => {
        setGroups(data);
        setLoading(false);
      })
  }, []);

  if (loading) {
    return <p>Loading...</p>;
  }

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <div className="App-intro">
          <h2>JUG List</h2>
          {groups.map(group =>
            <div key={group.id}>
              {group.name}
            </div>
          )}
        </div>
      </header>
    </div>
  );
}

export default App;

TIP: I learned a lot about React Hooks from Build a CRUD App in React with Hooks by Tania Rascia.

To proxy from /api to http://localhost:8080/api, add a proxy setting to app/package.json.

"scripts": {...},
"proxy": "http://localhost:8080",

To learn more about proxying API requests, see Create React App's documentation.

Make sure Spring Boot is running, then run npm start in your app directory. You should see the list of default groups.

Build a React `GroupList` component

React is all about components, and you don't want to render everything in your main App, so create app/src/GroupList.js and populate it with the following JavaScript.

import React, { useEffect, useState } from 'react';
import { Button, ButtonGroup, Container, Table } from 'reactstrap';
import AppNavbar from './AppNavbar';
import { Link } from 'react-router-dom';

const GroupList = () => {

  const [groups, setGroups] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    setLoading(true);

    fetch('api/groups')
      .then(response => response.json())
      .then(data => {
        setGroups(data);
        setLoading(false);
      })
  }, []);

  const remove = async (id) => {
    await fetch(`/api/group/${id}`, {
      method: 'DELETE',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      }
    }).then(() => {
      let updatedGroups = [...groups].filter(i => i.id !== id);
      setGroups(updatedGroups);
    });
  }

  if (loading) {
    return <p>Loading...</p>;
  }

  const groupList = groups.map(group => {
    const address = `${group.address || ''} ${group.city || ''} ${group.stateOrProvince || ''}`;
    return <tr key={group.id}>
      <td style={{whiteSpace: 'nowrap'}}>{group.name}</td>
      <td>{address}</td>
      <td>{group.events.map(event => {
        return <div key={event.id}>{new Intl.DateTimeFormat('en-US', {
          year: 'numeric',
          month: 'long',
          day: '2-digit'
        }).format(new Date(event.date))}: {event.title}</div>
      })}</td>
      <td>
        <ButtonGroup>
          <Button size="sm" color="primary" tag={Link} to={"/groups/" + group.id}>Edit</Button>
          <Button size="sm" color="danger" onClick={() => remove(group.id)}>Delete</Button>
        </ButtonGroup>
      </td>
    </tr>
  });

  return (
    <div>
      <AppNavbar/>
      <Container fluid>
        <div className="float-end">
          <Button color="success" tag={Link} to="/groups/new">Add Group</Button>
        </div>
        <h3>My JUG Tour</h3>
        <Table className="mt-4">
          <thead>
          <tr>
            <th width="20%">Name</th>
            <th width="20%">Location</th>
            <th>Events</th>
            <th width="10%">Actions</th>
          </tr>
          </thead>
          <tbody>
          {groupList}
          </tbody>
        </Table>
      </Container>
    </div>
  );
};

export default GroupList;

Create AppNavbar.js in the same directory to establish a common UI feature between components.

import React, { useState } from 'react';
import { Collapse, Nav, Navbar, NavbarBrand, NavbarToggler, NavItem, NavLink } from 'reactstrap';
import { Link } from 'react-router-dom';

const AppNavbar = () => {

  const [isOpen, setIsOpen] = useState(false);

  return (
    <Navbar color="dark" dark expand="md">
      <NavbarBrand tag={Link} to="/">Home</NavbarBrand>
      <NavbarToggler onClick={() => { setIsOpen(!isOpen) }}/>
      <Collapse isOpen={isOpen} navbar>
        <Nav className="justify-content-end" style={{width: "100%"}} navbar>
          <NavItem>
            <NavLink href="https://twitter.com/oktadev">@oktadev</NavLink>
          </NavItem>
          <NavItem>
            <NavLink href="https://github.com/oktadev/okta-spring-boot-react-crud-example">GitHub</NavLink>
          </NavItem>
        </Nav>
      </Collapse>
    </Navbar>
  );
};

export default AppNavbar;

Create app/src/Home.js to serve as the landing page for your app.

import React from 'react';
import './App.css';
import AppNavbar from './AppNavbar';
import { Link } from 'react-router-dom';
import { Button, Container } from 'reactstrap';

const Home = () => {
  return (
    <div>
      <AppNavbar/>
      <Container fluid>
        <Button color="link"><Link to="/groups">Manage JUG Tour</Link></Button>
      </Container>
    </div>
  );
}

export default Home;

Also, change app/src/App.js to use React Router to navigate between components.

import React from 'react';
import './App.css';
import Home from './Home';
import { BrowserRouter as Router, Route, Routes } from 'react-router-dom';
import GroupList from './GroupList';
import GroupEdit from './GroupEdit';

const App = () => {
  return (
    <Router>
      <Routes>
        <Route exact path="/" element={<Home/>}/>
        <Route path='/groups' exact={true} element={<GroupList/>}/>
      </Routes>
    </Router>
  )
}

export default App;

To make your UI a bit more spacious, add a top margin to Bootstrap's container classes in app/src/App.css.

nav + .container, nav + .container-fluid {
  margin-top: 20px;
}

Your React app should update itself as you make changes, and you should see a screen like the following at http://localhost:3000.

Click on Manage JUG Tour and you should see a list of the default groups.

It's great that you can see your Spring Boot API's data in your React app, but it's no fun if you can't edit it!

Add a React `GroupEdit` component

Create app/src/GroupEdit.js and use useEffect() to fetch the group resource with the ID from the URL.

import React, { useEffect, useState } from 'react';
import { Link, useNavigate, useParams } from 'react-router-dom';
import { Button, Container, Form, FormGroup, Input, Label } from 'reactstrap';
import AppNavbar from './AppNavbar';

const GroupEdit = () => {
  const initialFormState = {
    name: '',
    address: '',
    city: '',
    stateOrProvince: '',
    country: '',
    postalCode: ''
  };
  const [group, setGroup] = useState(initialFormState);
  const navigate = useNavigate();
  const { id } = useParams();

  useEffect(() => {
    if (id !== 'new') {
      fetch(`/api/group/${id}`)
        .then(response => response.json())
        .then(data => setGroup(data));
    }
  }, [id, setGroup]);

  const handleChange = (event) => {
    const { name, value } = event.target

    setGroup({ ...group, [name]: value })
  }

  const handleSubmit = async (event) => {
    event.preventDefault();

    await fetch(`/api/group${group.id ? `/${group.id}` : ''}`, {
      method: (group.id) ? 'PUT' : 'POST',
      headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(group)
    });
    setGroup(initialFormState);
    navigate('/groups');
  }

  const title = <h2>{group.id ? 'Edit Group' : 'Add Group'}</h2>;

  return (<div>
      <AppNavbar/>
      <Container>
        {title}
        <Form onSubmit={handleSubmit}>
          <FormGroup>
            <Label for="name">Name</Label>
            <Input type="text" name="name" id="name" value={group.name || ''}
                   onChange={handleChange} autoComplete="name"/>
          </FormGroup>
          <FormGroup>
            <Label for="address">Address</Label>
            <Input type="text" name="address" id="address" value={group.address || ''}
                   onChange={handleChange} autoComplete="address-level1"/>
          </FormGroup>
          <FormGroup>
            <Label for="city">City</Label>
            <Input type="text" name="city" id="city" value={group.city || ''}
                   onChange={handleChange} autoComplete="address-level1"/>
          </FormGroup>
          <div className="row">
            <FormGroup className="col-md-4 mb-3">
              <Label for="stateOrProvince">State/Province</Label>
              <Input type="text" name="stateOrProvince" id="stateOrProvince" value={group.stateOrProvince || ''}
                     onChange={handleChange} autoComplete="address-level1"/>
            </FormGroup>
            <FormGroup className="col-md-5 mb-3">
              <Label for="country">Country</Label>
              <Input type="text" name="country" id="country" value={group.country || ''}
                     onChange={handleChange} autoComplete="address-level1"/>
            </FormGroup>
            <FormGroup className="col-md-3 mb-3">
              <Label for="country">Postal Code</Label>
              <Input type="text" name="postalCode" id="postalCode" value={group.postalCode || ''}
                     onChange={handleChange} autoComplete="address-level1"/>
            </FormGroup>
          </div>
          <FormGroup>
            <Button color="primary" type="submit">Save</Button>{' '}
            <Button color="secondary" tag={Link} to="/groups">Cancel</Button>
          </FormGroup>
        </Form>
      </Container>
    </div>
  )
};

export default GroupEdit;

The useParams() hook is used to grab the ID from the URL and useNavigate() allows you to navigate back to the GroupList after adding or saving a group.

Modify app/src/App.js to import GroupEdit and specify a path to it.

import GroupEdit from './GroupEdit';

const App = () => {
  return (
    <Router>
      <Routes>
        ...
        <Route path='/groups/:id' element={<GroupEdit/>}/>
      </Routes>
    </Router>
  )
}

Now you should be able to add and edit groups!

Add authentication with Okta

It's pretty cool to build a CRUD app, but it's even cooler to build a secure one. To achieve that, you'll want to add authentication so users have to log in before viewing/modifying groups. To make this simple, you can use Okta's API for OIDC. At Okta, our goal is to make identity management a lot easier, more secure, and more scalable than what you're used to. Okta is a cloud service that allows developers to create, edit, and securely store user accounts and user account data, and connect them with one or multiple applications. Our API enables you to:

Authenticate and authorize your users
Store data about your users
Perform password-based and social login
Secure your application with multi-factor authentication
And much more! Check out our product documentation

Are you sold? Register for a forever-free developer account, and when you're done, come on back so you can learn more about building secure apps with Spring Boot!

Spring Security + OIDC

Spring Security added OIDC support in its 5.0 release. Since then, they've made quite a few improvements and simplified its required configuration. Add the Okta Spring Boot starter to do OIDC authentication.

<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-boot-starter</artifactId>
    <version>2.1.6</version>
</dependency>

This dependency is a thin wrapper around Spring Security's OAuth and encapsulates the following dependencies:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-config</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-oauth2-client</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-oauth2-jose</artifactId>
</dependency>

Create an OIDC app in Okta

Install the Okta CLI and run okta login. Then, run okta apps create. Select the default app name, or change it as you see fit. Choose Web and press Enter.

Select Okta Spring Boot Starter. Then, change the Redirect URI to http://localhost:8080/login/oauth2/code/okta and use http://localhost:3000,http://localhost:8080 for the Logout Redirect URI.

What does the Okta CLI do?

The Okta CLI will create an OIDC Web App in your Okta Org. It will add the redirect URIs you specified and grant access to the Everyone group. You will see output like the following when it’s finished:

Okta application configuration has been written to: 
  /path/to/app/src/main/resources/application.properties

Open src/main/resources/application.properties to see the issuer and credentials for your app.

okta.oauth2.issuer=https://dev-133337.okta.com/oauth2/default
okta.oauth2.client-id=0oab8eb55Kb9jdMIr5d6
okta.oauth2.client-secret=NEVER-SHOW-SECRETS

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

Use Auth0 for OIDC

If you'd rather use Auth0, that's possible too! First, you'll need to use the Spring Security dependencies as mentioned above. The Okta Spring Boot starter currently doesn't work with Auth0.

Then, install the Auth0 CLI and run auth0 login in a terminal.

Next, run auth0 apps create, provide a memorable name, and select Regular Web Application. Specify http://localhost:8080/login/oauth2/code/auth0 for the Callback URLs and http://localhost:3000,http://localhost:8080 for the Allowed Logout URLs.

Modify your src/main/resources/application.properties to include your Auth0 issuer, client ID, and client secret. You will have to run auth0 apps open and select the app you created to copy your client secret.

# make sure to include the trailing slash for the Auth0 issuer
spring.security.oauth2.client.provider.auth0.issuer-uri=https://<your-auth0-domain>/
spring.security.oauth2.client.registration.auth0.client-id=<your-client-id>
spring.security.oauth2.client.registration.auth0.client-secret=<your-client-secret>
spring.security.oauth2.client.registration.auth0.scope=openid,profile,email

Of course, you can also use your Auth0 dashboard to configure your application. Just make sure to use the same URLs specified above.

After configuring Spring Security in the section below, update UserController.java to use auth0 in its constructor:

public UserController(ClientRegistrationRepository registrations) {
    this.registration = registrations.findByRegistrationId("auth0");
}

And update its logout() method to work with Auth0:

@PostMapping("/api/logout")
public ResponseEntity<?> logout(HttpServletRequest request) {
    // send logout URL to client so they can initiate logout
    StringBuilder logoutUrl = new StringBuilder();
    String issuerUri = this.registration.getProviderDetails().getIssuerUri();
    logoutUrl.append(issuerUri.endsWith("/") ? issuerUri + "v2/logout" : issuerUri + "/v2/logout");
    logoutUrl.append("?client_id=").append(this.registration.getClientId());

    Map<String, String> logoutDetails = new HashMap<>();
    logoutDetails.put("logoutUrl", logoutUrl.toString());
    request.getSession(false).invalidate();
    return ResponseEntity.ok().body(logoutDetails);
}

You'll also need to update Home.js in the React project to use different parameters for the logout redirect:

window.location.href = `${response.logoutUrl}&returnTo=${window.location.origin}`;

You can see all the differences between Okta and Auth0 by comparing their branches on GitHub.

Configure Spring Security for React and user identity

To make Spring Security React-friendly, create a SecurityConfiguration.java file in src/main/java/.../jugtours/config. Create the config directory and put this class in it.

package com.okta.developer.jugtours.config;

import com.okta.developer.jugtours.web.CookieCsrfFilter;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.security.web.authentication.www.BasicAuthenticationFilter;
import org.springframework.security.web.csrf.CookieCsrfTokenRepository;
import org.springframework.security.web.csrf.CsrfTokenRequestAttributeHandler;
import org.springframework.security.web.savedrequest.HttpSessionRequestCache;
import org.springframework.security.web.savedrequest.RequestCache;
import org.springframework.security.web.savedrequest.SimpleSavedRequest;

@Configuration
public class SecurityConfiguration {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests((authz) -> authz
                .requestMatchers("/", "/index.html", "/static/**",
                    "/*.ico", "/*.json", "/*.png", "/api/user").permitAll()
                .anyRequest().authenticated()
            )
            .csrf((csrf) -> csrf
                .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse())
                .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler())
            )
            .addFilterAfter(new CookieCsrfFilter(), BasicAuthenticationFilter.class)
            .oauth2Login();
        return http.build();
    }

    @Bean
    public RequestCache refererRequestCache() { 
        return new HttpSessionRequestCache() {
            @Override
            public void saveRequest(HttpServletRequest request, HttpServletResponse response) {
                String referrer = request.getHeader("referer");
                if (referrer == null) {
                    referrer = request.getRequestURL().toString();
                }
                request.getSession().setAttribute("SPRING_SECURITY_SAVED_REQUEST",
                    new SimpleSavedRequest(referrer));

            }
        };
    }
}

This class has a lot going on, so let me explain a few things. In previous versions of Spring Security, there was an authorizeRequests() lambda you could use to secure paths. It still exists, but it's deprecated in Spring Security 6. It's permissive by default, which means any paths you don't specify will be allowed. The recommended way, shown here with authorizeHttpRequests() denies by default. This means you have to specify the resources you want to allow Spring Security to serve up, as well as the ones that the React app has.

The requestMatchers lines defines what URLs are allowed for anonymous users. You will soon configure things so your React app is served up by your Spring Boot app, hence the reason for allowing "/", "/index.html", and web files. You might also notice an exposed /api/user path.

The RequestCache bean overrides the default request cache. It saves the referrer header (misspelled referer in real life), so Spring Security can redirect back to it after authentication. The referrer-based request cache comes in handy when you're developing React on http://localhost:3000 and want to be redirected back there after logging in.

Configuring CSRF (cross-site request forgery) protection with CookieCsrfTokenRepository.withHttpOnlyFalse() means that the XSRF-TOKEN cookie won't be marked HTTP-only, so React can read it and send it back when it tries to manipulate data. The CsrfTokenRequestAttributeHandler is no longer the default, so you have to configure it as the request handler. You can read this Stack Overflow answer to learn more. Basically, since we're not sending the CSRF token to an HTML page, we don't have to worry about BREACH attacks. This means we can revert to the previous default from Spring Security 5.

You'll need to create the CookieCsrfFilter class that's added because Spring Security 6 no longer sets the cookie for you. Create it in the web package.

package com.okta.developer.jugtours.web;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.web.csrf.CsrfToken;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;

/**
 * Spring Security 6 doesn't set a XSRF-TOKEN cookie by default.
 * This solution is
 * <a href="https://github.com/spring-projects/spring-security/issues/12141#issuecomment-1321345077">
 * recommended by Spring Security.</a>
 */
public class CookieCsrfFilter extends OncePerRequestFilter {

  /**
   * {@inheritDoc}
   */
  @Override
  protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                  FilterChain filterChain) throws ServletException, IOException {
    CsrfToken csrfToken = (CsrfToken) request.getAttribute(CsrfToken.class.getName());
    response.setHeader(csrfToken.getHeaderName(), csrfToken.getToken());
    filterChain.doFilter(request, response);
  }
}

Create src/main/java/.../jugtours/web/UserController.java and populate it with the following code. This API will be used by React to 1) find out if a user is authenticated, and 2) perform global logout.

package com.okta.developer.jugtours.web;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.client.registration.ClientRegistration;
import org.springframework.security.oauth2.client.registration.ClientRegistrationRepository;
import org.springframework.security.oauth2.core.oidc.OidcIdToken;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import jakarta.servlet.http.HttpServletRequest;
import java.util.HashMap;
import java.util.Map;

@RestController
public class UserController {
    private ClientRegistration registration;

    public UserController(ClientRegistrationRepository registrations) {
        this.registration = registrations.findByRegistrationId("okta");
    }

    @GetMapping("/api/user")
    public ResponseEntity<?> getUser(@AuthenticationPrincipal OAuth2User user) {
        if (user == null) {
            return new ResponseEntity<>("", HttpStatus.OK);
        } else {
            return ResponseEntity.ok().body(user.getAttributes());
        }
    }

    @PostMapping("/api/logout")
    public ResponseEntity<?> logout(HttpServletRequest request,
                                    @AuthenticationPrincipal(expression = "idToken") OidcIdToken idToken) {
        // send logout URL to client so they can initiate logout
        String logoutUrl = this.registration.getProviderDetails()
                .getConfigurationMetadata().get("end_session_endpoint").toString();

        Map<String, String> logoutDetails = new HashMap<>();
        logoutDetails.put("logoutUrl", logoutUrl);
        logoutDetails.put("idToken", idToken.getTokenValue());
        request.getSession(false).invalidate();
        return ResponseEntity.ok().body(logoutDetails);
    }
}

You'll also want to add user information when creating groups so that you can filter by your JUG tour. Add a UserRepository.java in the same directory as GroupRepository.java.

package com.okta.developer.jugtours.model;

import org.springframework.data.jpa.repository.JpaRepository;

public interface UserRepository extends JpaRepository<User, String> {
}

Add a new findAllByUserId(String id) method to GroupRepository.java.

List<Group> findAllByUserId(String id);

Then inject UserRepository into GroupController.java and use it to create (or grab an existing user) when adding a new group. While you're there, modify the groups() method to filter by user.

package com.okta.developer.jugtours.web;

import com.okta.developer.jugtours.model.Group;
import com.okta.developer.jugtours.model.GroupRepository;
import com.okta.developer.jugtours.model.User;
import com.okta.developer.jugtours.model.UserRepository;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.web.bind.annotation.*;

import jakarta.validation.Valid;
import java.net.URI;
import java.net.URISyntaxException;
import java.security.Principal;
import java.util.Collection;
import java.util.Map;
import java.util.Optional;

@RestController
@RequestMapping("/api")
class GroupController {

    private final Logger log = LoggerFactory.getLogger(GroupController.class);
    private GroupRepository groupRepository;
    private UserRepository userRepository;

    public GroupController(GroupRepository groupRepository, UserRepository userRepository) {
        this.groupRepository = groupRepository;
        this.userRepository = userRepository;
    }

    @GetMapping("/groups")
    Collection<Group> groups(Principal principal) {
        return groupRepository.findAllByUserId(principal.getName());
    }

    @GetMapping("/group/{id}")
    ResponseEntity<?> getGroup(@PathVariable Long id) {
        Optional<Group> group = groupRepository.findById(id);
        return group.map(response -> ResponseEntity.ok().body(response))
                .orElse(new ResponseEntity<>(HttpStatus.NOT_FOUND));
    }

    @PostMapping("/group")
    ResponseEntity<Group> createGroup(@Valid @RequestBody Group group,
                                      @AuthenticationPrincipal OAuth2User principal) throws URISyntaxException {
        log.info("Request to create group: {}", group);
        Map<String, Object> details = principal.getAttributes();
        String userId = details.get("sub").toString();

        // check to see if user already exists
        Optional<User> user = userRepository.findById(userId);
        group.setUser(user.orElse(new User(userId,
                        details.get("name").toString(), details.get("email").toString())));

        Group result = groupRepository.save(group);
        return ResponseEntity.created(new URI("/api/group/" + result.getId()))
                .body(result);
    }

    @PutMapping("/group/{id}")
    ResponseEntity<Group> updateGroup(@Valid @RequestBody Group group) {
        log.info("Request to update group: {}", group);
        Group result = groupRepository.save(group);
        return ResponseEntity.ok().body(result);
    }

    @DeleteMapping("/group/{id}")
    public ResponseEntity<?> deleteGroup(@PathVariable Long id) {
        log.info("Request to delete group: {}", id);
        groupRepository.deleteById(id);
        return ResponseEntity.ok().build();
    }
}

To magnify the changes, they're in the groups() and createGroup() methods. It's pretty slick that Spring JPA will create the findAllByUserId() method/query for you and userRepository.findById() uses Java 8's Optional.

@GetMapping("/groups")
Collection<Group> groups(Principal principal) {
    return groupRepository.findAllByUserId(principal.getName());
}

@PostMapping("/group")
ResponseEntity<Group> createGroup(@Valid @RequestBody Group group,
                                  @AuthenticationPrincipal OAuth2User principal) throws URISyntaxException {
    log.info("Request to create group: {}", group);
    Map<String, Object> details = principal.getAttributes();
    String userId = details.get("sub").toString();

    // check to see if user already exists
    Optional<User> user = userRepository.findById(userId);
    group.setUser(user.orElse(new User(userId,
                    details.get("name").toString(), details.get("email").toString())));

    Group result = groupRepository.save(group);
    return ResponseEntity.created(new URI("/api/group/" + result.getId()))
            .body(result);
}

Modify React to handle CSRF and be identity-aware

You'll need to make a few changes to your React components to make them identity-aware. The first thing you'll want to do is modify src/index.js to wrap everything in a CookieProvider. This component allows you to read the CSRF cookie and send it back as a header.

import { CookiesProvider } from 'react-cookie';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <CookiesProvider>
      <App/>
    </CookiesProvider>
  </React.StrictMode>
);

Modify app/src/Home.js to call /api/user to see if the user is logged in. If they're not, show a Login button.

import React, { useEffect, useState } from 'react';
import './App.css';
import AppNavbar from './AppNavbar';
import { Link } from 'react-router-dom';
import { Button, Container } from 'reactstrap';
import { useCookies } from 'react-cookie';

const Home = () => {

  const [authenticated, setAuthenticated] = useState(false);
  const [loading, setLoading] = useState(false);
  const [user, setUser] = useState(undefined);
  const [cookies] = useCookies(['XSRF-TOKEN']);

  useEffect(() => {
    setLoading(true);
    fetch('api/user', { credentials: 'include' })
      .then(response => response.text())
      .then(body => {
        if (body === '') {
          setAuthenticated(false);
        } else {
          setUser(JSON.parse(body));
          setAuthenticated(true);
        }
        setLoading(false);
      });
  }, [setAuthenticated, setLoading, setUser])

  const login = () => {
    let port = (window.location.port ? ':' + window.location.port : '');
    if (port === ':3000') {
      port = ':8080';
    }
    // redirect to a protected URL to trigger authentication
    window.location.href = `//${window.location.hostname}${port}/api/private`;
  }

  const logout = () => {
    fetch('/api/logout', {
      method: 'POST', credentials: 'include',
      headers: { 'X-XSRF-TOKEN': cookies['XSRF-TOKEN'] }
    })
      .then(res => res.json())
      .then(response => {
        window.location.href = `${response.logoutUrl}?id_token_hint=${response.idToken}`
          + `&post_logout_redirect_uri=${window.location.origin}`;
      });
  }

  const message = user ?
    <h2>Welcome, {user.name}!</h2> :
    <p>Please log in to manage your JUG Tour.</p>;

  const button = authenticated ?
    <div>
      <Button color="link"><Link to="/groups">Manage JUG Tour</Link></Button>
      <br/>
      <Button color="link" onClick={logout}>Logout</Button>
    </div> :
    <Button color="primary" onClick={login}>Login</Button>;

  if (loading) {
    return <p>Loading...</p>;
  }

  return (
    <div>
      <AppNavbar/>
      <Container fluid>
        {message}
        {button}
      </Container>
    </div>
  );
}

export default Home;

There are some things you should be aware of in this component:

useCookies() is used for access to cookies. Then you can fetch a cookie with cookies['XSRF-TOKEN'].
When using fetch(), you need to include {credentials: 'include'} to transfer cookies. You will get a 403 Forbidden if you do not include this option.
The CSRF cookie from Spring Security has a different name than the header you need to send back. The cookie name is XSRF-TOKEN, while the header name is X-XSRF-TOKEN.

Update app/src/GroupList.js to have similar changes. The good news is you don't need to make any changes to the render() method.

import { useCookies } from 'react-cookie';

const GroupList = () => {

  ...
  const [cookies] = useCookies(['XSRF-TOKEN']);

  ...
  const remove = async (id) => {
    await fetch(`/api/group/${id}`, {
      method: 'DELETE',
      headers: {
        'X-XSRF-TOKEN': cookies['XSRF-TOKEN'],
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      credentials: 'include'
    }).then(() => {
      let updatedGroups = [...groups].filter(i => i.id !== id);
      setGroups(updatedGroups);
    });
  }
  ...

  return (...)
}

export default GroupList;

Update GroupEdit.js too.

import { useCookies } from 'react-cookie';

const GroupEdit = () => {

  ...
  const [cookies] = useCookies(['XSRF-TOKEN']);

  ...
  const handleSubmit = async (event) => {
    event.preventDefault();

    await fetch(`/api/group${group.id ? `/${group.id}` : ''}`, {
      method: group.id ? 'PUT' : 'POST',
      headers: {
        'X-XSRF-TOKEN': cookies['XSRF-TOKEN'],
        'Accept': 'application/json',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(group),
      credentials: 'include'
    });
    setGroup(initialFormState);
    navigate('/groups');
  }

  ...

  return (...)
}

export default GroupEdit;

After all these changes, you should be able to restart both Spring Boot and React and witness the glory of planning your very own JUG Tour!

Configure Maven to build and package React with Spring Boot

To build and package your React app with Maven, you can use the frontend-maven-plugin and Maven's profiles to activate it. Add properties for versions and a <profiles> section to your pom.xml.

<properties>
    ...
    <frontend-maven-plugin.version>1.12.1</frontend-maven-plugin.version>
    <node.version>v16.18.1</node.version>
    <npm.version>v8.19.2</npm.version>
</properties>

<profiles>
    <profile>
        <id>dev</id>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <spring.profiles.active>dev</spring.profiles.active>
        </properties>
    </profile>
    <profile>
        <id>prod</id>
        <build>
            <plugins>
                <plugin>
                    <artifactId>maven-resources-plugin</artifactId>
                    <executions>
                        <execution>
                            <id>copy-resources</id>
                            <phase>process-classes</phase>
                            <goals>
                                <goal>copy-resources</goal>
                            </goals>
                            <configuration>
                                <outputDirectory>${basedir}/target/classes/static</outputDirectory>
                                <resources>
                                    <resource>
                                        <directory>app/build</directory>
                                    </resource>
                                </resources>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
                <plugin>
                    <groupId>com.github.eirslett</groupId>
                    <artifactId>frontend-maven-plugin</artifactId>
                    <version>${frontend-maven-plugin.version}</version>
                    <configuration>
                        <workingDirectory>app</workingDirectory>
                    </configuration>
                    <executions>
                        <execution>
                            <id>install node</id>
                            <goals>
                                <goal>install-node-and-npm</goal>
                            </goals>
                            <configuration>
                                <nodeVersion>${node.version}</nodeVersion>
                                <npmVersion>${npm.version}</npmVersion>
                            </configuration>
                        </execution>
                        <execution>
                            <id>npm install</id>
                            <goals>
                                <goal>npm</goal>
                            </goals>
                            <phase>generate-resources</phase>
                        </execution>
                        <execution>
                            <id>npm test</id>
                            <goals>
                                <goal>test</goal>
                            </goals>
                            <phase>test</phase>
                            <configuration>
                                <arguments>test</arguments>
                                <environmentVariables>
                                    <CI>true</CI>
                                </environmentVariables>
                            </configuration>
                        </execution>
                        <execution>
                            <id>npm build</id>
                            <goals>
                                <goal>npm</goal>
                            </goals>
                            <phase>compile</phase>
                            <configuration>
                                <arguments>run build</arguments>
                            </configuration>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
        <properties>
            <spring.profiles.active>prod</spring.profiles.active>
        </properties>
    </profile>
</profiles>

While you're at it, add the active profile setting to src/main/resources/application.properties:

spring.profiles.active=@spring.profiles.active@

After adding this, you should be able to run ./mvnw spring-boot:run -Pprod and see your app running on http://localhost:8080.

Everything will work just fine if you start at the root, since React will handle routing. However, if you refresh the page when you're at http://localhost:8080/groups, you'll get a 404 error since Spring Boot doesn't have a route for /groups. To fix this, add a SpaWebFilter that conditionally forwards to the React app.

package com.okta.developer.jugtours.web;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.oauth2.core.user.OAuth2User;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.security.Principal;

public class SpaWebFilter extends OncePerRequestFilter {

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String path = request.getRequestURI();
        Authentication user = SecurityContextHolder.getContext().getAuthentication();
        if (user != null && !path.startsWith("/api") && !path.contains(".") && path.matches("/(.*)")) {
            request.getRequestDispatcher("/").forward(request, response);
            return;
        }

        filterChain.doFilter(request, response);
    }
}

And, add it to SecurityConfiguration.java:

.addFilterAfter(new SpaWebFilter(), BasicAuthenticationFilter.class)

Now, if you restart and reload the page, everything will work as expected. 🤗

Learn more about Spring Boot and React

I hope you've enjoyed this tutorial on how to do CRUD with React, Spring Boot, and Spring Security. You can see that Spring Security's OIDC support is pretty robust, and doesn't require a whole lot of configuration. Adding CSRF protection and packaging your Spring Boot + React app as a single artifact is pretty cool too!

You can find the example created in this tutorial on GitHub at https://github.com/oktadev/okta-spring-boot-react-crud-example.

We've written some other cool Spring Boot and React tutorials. Check them out if you're interested.

If you have any questions, please don't hesitate to leave a comment below or ask us on our Okta Developer Forums. Follow us on Twitter if you want to see more tutorials like this one!

Build Secure Ionic Apps with Angular and JHipster

Matt Raible — Thu, 16 Jun 2022 23:43:08 +0000

Ionic is a framework for building mobile apps with web technologies that look and act like native apps. Because they're built with web technologies (HTML, JavaScript, and CSS), you can also deploy your Ionic apps as single-page applications. Or, even better, as progressive web apps (PWAs) that work offline.

Ionic supports the big three web frameworks: Angular, React, and Vue. Once you've written your app, you can deploy it to a simulator or device with Capacitor. Capacitor (pictured as the blue layer) provides the runtime for your app to communicate with the native operating system and vice versa.

Ionic's main competitors are native apps built with Swift or Objective-C (for iOS) and Java or Kotlin (for Android). Ionic also competes with React Native, which uses web technologies and translates them to native components.

The Ionic blog has a recent post that does a performance comparison between Ionic and React Native. TL;DR: Both options will give you a high-performance app with a truly native look and feel.

Prerequisites:

What the heck is JHipster?

This tutorial will show you how to use Ionic, Angular, and Capacitor to build a mobile app that talks to a Spring Boot backend. It won't take but a few minutes, thanks to JHipster!

JHipster is an application generator that creates an Angular frontend and a Spring Boot backend based on the options you choose. It has the ability for you, as a developer, to customize what it generates with blueprints. The blueprints feature has resulted in many additional options for an app: Kotlin, Spring Native, Micronaut, Quarkus, .NET Core, NestJS, and Svelte.

Below is a diagram of the app you'll create in this tutorial and its authentication flow.

✨ Introducing the JHipster Ionic blueprint!

The JHipster project has supported generating an Ionic app using a generator-jhipster-ionic module for the past several years.
As the primary maintainer of this module, I'm proud to announce that it has been re-written as a blueprint, and it's much easier to understand now. The previous module relied on the Ionic CLI, the base Angular starter, the Ionic JHipster starter, and custom code to glue it all together.
Now, the source code is all contained in one project.

Marcelo Shima volunteered to do the conversion, and after a couple of months, I'm proud to say the JHipster Ionic blueprint is now available!

// Detect dark theme var iframe = document.getElementById('tweet-1523893356744609792-214'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1523893356744609792&theme=dark" }

Here's how to use it:

Create an ionic-app directory alongside your JHipster app.

- backend
- ionic-app

Navigate into ionic-app using your terminal. Install Ionic for JHipster and create a new app using jhipster-ionic.

npm install -g generator-jhipster-ionic
jhipster-ionic

You'll be prompted for the location of your JHipster app, a name for your Ionic app, and then you'll be off to the races!

You can also create a JHipster app and an Ionic app simultaneously by using the bundled JHipster.

mkdir bug-tracker && cd bug-tracker
jhipster-ionic jdl bug-tracker.jh
cd ../ionic4j

This process will follow the same convention where the generated backend and frontend apps are side-by-side on your hard drive.

Then you can run both apps from your Ionic app using easy-to-remember commands.

npm run backend:start
# open a new terminal window
npm start

NOTE: The JHipster Ionic blueprint currently only supports Angular. Now that it's a blueprint, it will be much easier to add support for Vue and React. If you're interested in helping out, please let me know! Okta is a platinum sponsor of the JHipster project and enjoys assigning bug bounties for feature development.

Build a mobile app with Ionic and Angular

To see Ionic + JHipster in action, let's start with a Full Stack Java + React app I created for the Auth0 blog. I updated the app to the latest version of JHipster (v7.8.1) and created an Ionic app with JHipster Ionic, so everything is guaranteed to work. This Flickr clone allows you to upload photos, tag them, and organize them into albums. First, clone the example:

git clone https://github.com/oktadev/okta-jhipster-ionic-example.git \
  jhipster-ionic --depth 1
cd jhipster-ionic/backend

Start the app:

npm run ci:e2e:prepare # starts Keycloak and PostgreSQL in Docker
./mvnw

Then, navigate to http://localhost:8080 in your favorite browser.
Sign in with admin/admin credentials and rejoice when it all works.

Open a new terminal window and enter the jhipster-ionic/ionic-app directory. Install its dependencies and run npm start to test the Ionic client.

npm install
npm start

You should be able to sign in and add a new photo.

Please keep reading to learn how JHipster made all of this possible. Or, skip ahead to run your Ionic app on iOS using Capacitor.

How to integrate Ionic and Spring Boot

JHipster makes it easy to create a Spring Boot API that Spring Security protects. The JHipster Ionic blueprint generates an Ionic client that talks to your Spring Boot API and understands its auth mechanism. I created the jhipster-ionic project using the following steps:

Install the JHipster Ionic blueprint:

npm i -g generator-jhipster-ionic@8.0.0

Create a parent directory to hold everything:

# take is a shortcut for mdkir && cd
take jhipster-ionic

Clone an existing JHipster Flickr example:

git clone https://github.com/oktadev/auth0-full-stack-java-example.git backend --depth 1

Create a new directory to hold your Ionic project, then run jhipster-ionic in it:

take ionic-app
jhipster-ionic

Provide the path to your backend JHipster app and name your app flickr2.

That's it! The blueprint will generate an Ionic client, complete with screens for editing entities, unit tests, and end-to-end tests with Cypress.

Pretty slick, don't you think?! 😎

Run your Spring Boot API

You'll need to start your backend first, so your Ionic app can talk to its API. First, start Keycloak and PostgreSQL in Docker containers:

cd backend
npm run ci:e2e:prepare # starts Keycloak and PostgreSQL in Docker

Next, update backend/src/main/resources/config/application-prod.yml to allow CORS from http://localhost:8100.

jhipster:
  ...
  cors:
    allowed-origins: 'http://localhost:8100'
    allowed-methods: '*'
    allowed-headers: '*'
    exposed-headers: 'Authorization,Link,X-Total-Count,X-${jhipster.clientApp.name}-alert,X-${jhipster.clientApp.name}-error,X-${jhipster.clientApp.name}-params'
    allow-credentials: true
    max-age: 1800

Then, start the backend app using ./mvnw -Pprod. You should be able to log in at http://localhost:8080 (with admin/admin) and add new photos using Entities > Photos. Add a few photos so you have some data to work with.

Run your Ionic app

Open another terminal and navigate to the ionic-app folder. Launch your Ionic client using npm start. In your default browser, the app will be opened at http://localhost:8100.

You should be able to log in with Keycloak and see all the listed entities in your app.

In the JHipster app's tutorial, there's a section where you're instructed to remove photo fields that can be calculated. Specifically, height, width, date taken, and date uploaded. These values are calculated when the photos are uploaded, so there's no reason to display them when adding a photo.

To add this same functionality to your Ionic app, modify src/app/pages/entities/photo/photo-update.html and wrap these fields with <div *ngIf="!isNew">.

<div *ngIf="!isNew">
  <ion-item>
    <ion-label position="floating">Height</ion-label>
    <ion-input type="number" name="height" formControlName="height"></ion-input>
  </ion-item>
  ...
  <ion-item>
    <ion-label>Uploaded</ion-label>
    <ion-datetime displayFormat="MM/DD/YYYY HH:mm" formControlName="uploaded" id="field_uploaded"></ion-datetime>
  </ion-item>
</div>

The Ionic CLI will auto-compile and reload the app in your browser when you save this file. You can prove everything works as expected by stopping your app (with Ctrl + C) and running all the end-to-end tests with Cypress.

npm run e2e

Run your Ionic app on iOS using Capacitor

Generate a native iOS project with the following commands:

npx ionic build
npx ionic capacitor add ios

Add your custom scheme (dev.localhost.ionic) to ios/App/App/Info.plist. This scheme is configured in src/environments/environment.ts; you can easily change it to something else if you like.

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>com.getcapacitor.capacitor</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>capacitor</string>
      <string>dev.localhost.ionic</string>
    </array>
  </dict>
</array>

Modify the JHipster app's CORS settings (in backend/src/main/resources/config/application-prod.yml) to allow capacitor://localhost as an origin.

jhipster:
  ...
  cors:
    allowed-origins: 'http://localhost:8100,capacitor://localhost'

Restart your backend app. Deploy your Ionic app to iOS Simulator and run it.

npx cap run ios

Confirm you can log in and rejoice in your success!

Run your Ionic app on Android

Generate an Android project with Capacitor.

npx ionic capacitor add android

Enable clear text traffic and add dev.localhost.ionic as a scheme in android/app/src/main/AndroidManifest.xml:

<activity ... android:usesCleartextTraffic="true">
  <!-- You'll need to add this intent filter so redirects work -->
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="dev.localhost.ionic" />
    <!--data android:scheme="com.okta.dev-133337" /-->
  </intent-filter>

  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>
</activity>

Modify the JHipster app's CORS settings to allow http://localhost as an origin.

jhipster:
  ...
  cors:
    allowed-origins: 'http://localhost:8100,capacitor://localhost,http://localhost'

Restart your backend app and run your Ionic app on Android using the Capacitor CLI:

npx cap run android

CAUTION: If you get an error when running this command, make sure to use Java 11.

You'll need to run a couple of commands to allow the emulator to communicate with JHipster and Keycloak.

adb reverse tcp:8080 tcp:8080
adb reverse tcp:9080 tcp:9080

You should be able to log in and edit entities, just like you can in a browser and on iOS!

Why use OpenID Connect for mobile apps?

Storing API keys and secrets in mobile apps is not safe. OAuth 2.0 solves this problem by not shipping any secrets in mobile apps and instead involving the user in the process of getting an access token into the app. These access tokens are unique per user, and they're updated every time the user logs in. The PKCE extension provides a solution for securely doing the OAuth flow on a mobile app even when there is no pre-provisioned secret.

If you need to access an API from a mobile app, hopefully, it supports OAuth and PKCE! Thankfully most of the hard work of PKCE is handled by SDKs like AppAuth, so you don't have to write all that code yourself. If you're working with an API like Okta, then Okta's SDKs do PKCE automatically, so you don't have to worry about it. The JHipster Ionic blueprint uses Ionic AppAuth.

The previous sections showed you how to use Keycloak as your identity provider. If you're deploying to production, you might not want to manage your users and authentication system. That's where Okta and Auth0 can help!

Switch your identity provider to Okta

If you don't have an Okta developer account, you can sign up for one or run okta register after installing the Okta CLI.

If you want to change your JHipster app to use Okta, the Okta CLI makes this as easy as okta apps create jhipster. This command creates a .okta.env file you can source to override the default Keycloak settings.

source .okta.env
./mvnw -Pprod

With Keycloak, you don't need a separate OIDC app for Ionic. With Okta, you do. See JHipster's documentation to learn how to create a native app for Ionic on Okta.

After you've changed the client ID in your Ionic app, run it using npm start. You'll be prompted to log in using your Okta credentials at http://localhost:8100.

Switch your identity provider to Auth0

To switch your identity provider to Auth0, you first need an Auth0 account. Then, create a .auth0.env file and see JHipster's Auth0 docs for how to populate it.

Next, configure a native app for Ionic on Auth0. Once you're finished updating your Ionic app with a new client ID and audience, you should be able to run your backend and new frontend client using the following commands:

source .auth0.env
npm run backend:start
# open a new terminal
npm start

To see it in action on your mobile emulators, use the following commands:

npm run build

# iOS
npx cap run ios

# Android
npx cap run android

Learn more about Ionic, Spring Boot, and JHipster

I hope you've enjoyed learning about Ionic and the new Ionic blueprint for JHipster. In my opinion, it's pretty neat that you can rapidly prototype a mobile client for your JHipster. It's even better that you can use a leading-edge mobile application framework to do it.

You can find the source code for this example on GitHub, in the @oktadev/okta-jhipster-ionic-example repository.

If you liked this post, you might like these others too.

If you have any questions, please leave a comment below.
You can follow @oktadev on Twitter and subscribe to our YouTube channel for more leading-edge content. We're also on LinkedIn and Facebook.

Introducing Spring Native for JHipster: Serverless Full-Stack Made Easy

Matt Raible — Thu, 24 Mar 2022 16:49:18 +0000

Over the years, I've developed a lot of Java applications. I started writing Java code in the late 90s and spent several years doing Java before I tried another server-side language. I was impressed when I first tried building apps in Ruby on Rails, Python, and Node.js - they all started super-fast!

Starting fast is cool, but we in the Java community have often asked, does it perform over time? The Java Virtual Machine is famous for performance and optimization over time.

I scoffed at serverless when it first came out. Mostly because I was a Java developer and my apps didn't start in milliseconds. They also used a whole lotta memory and there was no hope in sight.

Then, along came GraalVM. It's gained support from many Java frameworks in the last few years and has made their apps start in milliseconds!

Today, I'm proud to announce that this same capability is now available for your JHipster 7+ apps!

Prerequisites:

If you'd rather learn visually, you can watch a video of this tutorial.

Why should you care about serverless?

From IBM's What is Serverless computing?

Serverless is a cloud execution model that enables a simpler, more cost-effective way to build and operate cloud-native applications.

That's it!

For companies with high traffic and large cloud bills, serverless makes sense. They can save millions of dollars a month.

GraalVM allows serverless Java for everyone!

I've been playing with GraalVM and the Java frameworks that support it for around 18 months. After doing a lot of research, I blogged about building native Java apps with Micronaut, Quarkus, and Spring Boot.

In September 2021, I did a talk with Josh Long about Spring Native with JHipster at the San Francisco JUG.

// Detect dark theme var iframe = document.getElementById('tweet-1442698739563446276-977'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1442698739563446276&theme=dark" }

I flew out on a Monday, we got everything working by Wednesday afternoon, and then spoke about our experience on Wednesday night. I wrote about it in JHipster Works with Spring Native! on LinkedIn and created a JHipster issue to automate our learnings.

What is Spring Native?

Spring Native provides an API to configure Spring Boot and GraalVM so classes that are not easily discoverable become recognizable. For example, those that are instantiated using reflection. It's a really slick extension to Spring Boot and will likely disappear with Spring Boot 3 because it'll be native by default.

As a result of our successful presentation at the SF JUG, Josh and I were invited to speak at the Garden State JUG in December. We laid low for a few months and rekindled our research in December. I wrote about it in JHipster works with Spring Native, Part 2!

🔥 Announcing the JHipster Native blueprint!

In late January 2022, we (the JHipster team) upgraded JHipster to use Spring Boot 2.6 and released version 7.6.0.

In early February, I updated the Spring Native with JHipster examples that Josh and I'd been using for research. I was ready to start automating the Spring Native integration using a JHipster module. When I asked the JHipster team about the best way to implement it, Marcelo Shima volunteered to create the initial blueprint.

This was on a Friday afternoon (Mountain Time or MT). By the next morning, Marcelo had the MVP finished and provided steps to reproduce our examples. 😳

I was amazed! I remember telling (my partner) Trish that he'd done a week's worth of (my estimated) work in a matter of hours.

Today, I'm proud to announce the JHipster Native blueprint is available! Here's how to use it:

npm install -g generator-jhipster-native
jhipster-native

This will generate a JHipster app and integrate GraalVM automatically. You can build and run a native image with the following commands:

./mvnw package -Pnative,prod -DskipTests
npm run ci:e2e:prepare # start docker dependencies
./target/native-executable

NOTE: Gradle is not currently an option. Follow generator-jhipster-native#24 to see when it's supported.

Go native with Spring Native and GraalVM

To see Spring Native + JHipster in action, let's look at a previous JHipster app I created for the Auth0 blog. First, clone the example:

git clone https://github.com/oktadev/auth0-full-stack-java-example.git jhipster-native
cd jhipster-native

TIP: Want results right away? Clone the spring-native branch with the changes below already made:
git clone -b spring-native https://github.com/oktadev/auth0-full-stack-java-example.git jhipster-native
Then, skip to the Configure your OpenID Connect identity provider section to continue.

Install JHipster 7.8.1 and the JHipster Native blueprint:

npm i -g generator-jhipster@7.8.1
npm i -g generator-jhipster-native@1.1.2

Then, remove all the existing project files and regenerate them. The jhipster-native command includes parameters to disable caching because it's not supported by Spring Native, yet.

rm -rf *
jhipster-native --with-entities --cache-provider no --no-enable-hibernate-cache
# When prompted to overwrite .gitignore, type "a" to overwrite all files

If you open the project in IntelliJ IDEA, you can use the Commit Tools Window (Cmd + 0 on macOS or Ctrl + 0 on Linux/Windows) to view files that changed.

Next, run the following git checkout commands to restore the files that were modified in the original example.

git checkout .gitignore
git checkout README.md
git checkout demo.adoc
git checkout flickr2.jdl
git checkout screenshots
git checkout src/main/webapp/app/entities/photo/photo.tsx
git checkout src/main/webapp/app/entities/photo/photo-update.tsx
git checkout src/main/java/com/auth0/flickr2/config/SecurityConfiguration.java
git checkout src/main/resources/config/application-heroku.yml
git checkout src/main/resources/config/bootstrap-heroku.yml
git checkout Procfile
git checkout system.properties

If you'd rather not use the command line, you can right-click on each file and select Rollback.

If you ran the git checkout commands, there are several changes I made in the first tutorial that'll need to be re-applied:

In src/main/resources/config/application-dev.yml, remove the faker profile for Liquibase.

In pom.xml, re-add Drew Noake's metadata-extractor library:

<dependency>
    <groupId>com.drewnoakes</groupId>
    <artifactId>metadata-extractor</artifactId>
    <version>2.16.0</version>
</dependency>

Next, modify the createPhoto() method in src/main/java/com/auth0/flickr2/web/rest/PhotoResource.java to set the metadata when an image is uploaded.

import com.drew.imaging.ImageMetadataReader;
import com.drew.imaging.ImageProcessingException;
import com.drew.metadata.Metadata;
import com.drew.metadata.MetadataException;
import com.drew.metadata.exif.ExifSubIFDDirectory;
import com.drew.metadata.jpeg.JpegDirectory;

import javax.xml.bind.DatatypeConverter;
import java.io.BufferedInputStream;
import java.io.ByteArrayInputStream;
import java.io.IOException;
import java.io.InputStream;

import java.time.Instant;
import java.util.Date;

public class PhotoResource {
    ...

    public ResponseEntity<Photo> createPhoto(@Valid @RequestBody Photo photo) throws URISyntaxException {
        log.debug("REST request to save Photo : {}", photo);
        if (photo.getId() != null) { ... }

        try {
            photo = setMetadata(photo);
        } catch (ImageProcessingException | IOException | MetadataException ipe) {
            log.error(ipe.getMessage());
        }

        Photo result = photoRepository.save(photo);
        ...
    }

    private Photo setMetadata(Photo photo) throws ImageProcessingException, IOException, MetadataException {
        String str = DatatypeConverter.printBase64Binary(photo.getImage());
        byte[] data2 = DatatypeConverter.parseBase64Binary(str);
        InputStream inputStream = new ByteArrayInputStream(data2);
        BufferedInputStream bis = new BufferedInputStream(inputStream);
        Metadata metadata = ImageMetadataReader.readMetadata(bis);
        ExifSubIFDDirectory directory = metadata.getFirstDirectoryOfType(ExifSubIFDDirectory.class);

        if (directory != null) {
            Date date = directory.getDateDigitized();
            if (date != null) {
                photo.setTaken(date.toInstant());
            }
        }

        if (photo.getTaken() == null) {
            log.debug("Photo EXIF date digitized not available, setting taken on date to now...");
            photo.setTaken(Instant.now());
        }

        photo.setUploaded(Instant.now());

        JpegDirectory jpgDirectory = metadata.getFirstDirectoryOfType(JpegDirectory.class);
        if (jpgDirectory != null) {
            photo.setHeight(jpgDirectory.getImageHeight());
            photo.setWidth(jpgDirectory.getImageWidth());
        }

        return photo;
    }
    ...
}

Install the React libraries needed:
```
npm i react-photo-album react-images
```
IMPORTANT: In the previous tutorial, I used react-photo-gallery. I switched to react-photo-album because it supports React 17. Because of this, you'll also need to update src/main/webapp/app/entities/photo/photo.tsx.
1. Change import Gallery from 'react-photo-gallery' to import PhotoAlbum from 'react-photo-album'.
2. Change <Gallery photos={photoSet} onClick={openLightbox} /> to <PhotoAlbum photos={photoSet} layout="rows" onClick={openLightbox} />.

In src/test/javascript/cypress/integration/entity/photo.spec.ts, remove the code that sets the calculated data in the should create an instance of Photo test:

cy.get(`[data-cy="height"]`).type('99459').should('have.value', '99459');
cy.get(`[data-cy="width"]`).type('61514').should('have.value', '61514');
cy.get(`[data-cy="taken"]`).type('2021-10-11T16:46').should('have.value', '2021-10-11T16:46');
cy.get(`[data-cy="uploaded"]`).type('2021-10-11T15:23').should('have.value', '2021-10-11T15:23');

Then, you'll need to add type hints for Drew Noake's EXIF processing library in src/main/java/com/auth0/flickr2/Flickr2App.java:

@org.springframework.nativex.hint.TypeHint(
    types = {
        ...
        com.drew.metadata.exif.ExifIFD0Directory.class,
        com.drew.metadata.exif.ExifSubIFDDirectory.class,
        com.drew.metadata.exif.ExifThumbnailDirectory.class,
        com.drew.metadata.exif.makernotes.AppleMakernoteDirectory.class,
        com.drew.metadata.exif.GpsDirectory.class,
})
@org.springframework.nativex.hint.NativeHint(options = "-H:+AddAllCharsets")

The @NativeHint(options = "-H:+AddAllCharsets") solves the following exception that happens when you upload a photo:

Caused by: java.nio.charset.UnsupportedCharsetException: Cp1252
    at java.nio.charset.Charset.forName(Charset.java:528) ~[native-executable:na]
    at com.drew.lang.Charsets.<clinit>(Charsets.java:40) ~[na:na]

Once you've made all the changes (or cloned the spring-native branch), you can build your hip native binary.

Build a native JHipster app

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 22.0.0.2.r17-grl

Then, use Maven to build the project. Skip tests since there's no support for Mockito at this time.

./mvnw package -Pnative,prod -DskipTests

This process will take a few minutes to complete.

Configure your OpenID Connect identity provider

When you generate a JHipster app with OAuth 2.0 / OIDC for authentication, it defaults to using Keycloak. It creates a src/main/docker/keycloak.yml file for Docker Compose, as well as a src/main/docker/realm-config directory with files to auto-create users and OIDC clients.

If you want to use Keycloak for your running app, start it with the following command:

docker-compose -f src/main/docker/keycloak.yml up -d

If you'd rather use Okta or Auth0, that's possible too!

Use Okta as your identity provider

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 jhipster. Select the default app name, or change it as you see fit. Accept the default Redirect URI values provided for you.

You'll need to source the .okta.env file the Okta CLI creates to override the default Spring Security settings.

source .okta.env

If you're on Windows, you can modify this file to use set instead of export and rename it to okta.bat. Then, run it with okta.bat from the command line.

CAUTION: Modify your existing .gitignore file to have *.env so you don't accidentally check in your secrets!

Skip to Run your native JHipster app if you've configured your app for Okta and just want to see it running.

Use Auth0 as your identity provider

To switch from Keycloak to Auth0, override the Spring Security OAuth properties. You don't even need to write any code!

To see how it works, create a .auth0.env file in the root of your project, and fill it with the code below to override the default OIDC settings:

export SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_OIDC_ISSUER_URI=https://<your-auth0-domain>/
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_ID=<your-client-id>
export SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_OIDC_CLIENT_SECRET=<your-client-secret>
export JHIPSTER_SECURITY_OAUTH2_AUDIENCE=https://<your-auth0-domain>/api/v2/

You'll need to create a new web application in Auth0 and fill in the <...> placeholders before this works.

Create an OpenID Connect app on Auth0

Log in to your Auth0 account (or sign up if you don't have an account). You should have a unique domain like dev-xxx.eu.auth0.com.

Press the Create Application button in the Applications section. Use a name like JHipster Native!, select Regular Web Applications, and click Create.

Switch to the Settings tab and configure your application settings:

Allowed Callback URLs: http://localhost:8080/login/oauth2/code/oidc
Allowed Logout URLs: http://localhost:8080/

Scroll to the bottom and click Save Changes.

Copy your Auth0 domain, client ID, and client secret into the .auth0.env file you created earlier. Then, run source .auth0.env.

In the roles section, create new roles named ROLE_ADMIN and ROLE_USER.

Create a new user account in the users section. Click on the Role tab to assign the roles you just created to the new account.

Make sure your new user's email is verified before attempting to log in!

Next, head to Auth Pipeline > Rules > Create. Select the Empty rule template. Provide a meaningful name like Group claims and replace the Script content with the following.

function(user, context, callback) {
  user.preferred_username = user.email;
  const roles = (context.authorization || {}).roles;

  function prepareCustomClaimKey(claim) {
    return `https://www.jhipster.tech/${claim}`;
  }

  const rolesClaim = prepareCustomClaimKey('roles');

  if (context.idToken) {
    context.idToken[rolesClaim] = roles;
  }

  if (context.accessToken) {
    context.accessToken[rolesClaim] = roles;
  }

  callback(null, user, context);
}

This code is adding the user's roles to a custom claim (prefixed with https://www.jhipster.tech/roles). Click Save changes to continue.

TIP: Want to have all these steps automated for you? Add a 👍 to issue #351 in the Auth0 CLI project.

Run your native JHipster app

After you've built your app, it will be available in target/native-executable. Start Keycloak or source your Okta/Auth0 settings. Then, run the following commands:

npm run ci:e2e:prepare # start docker dependencies
./target/native-executable

It should start in under a second!

What does the JHipster Native blueprint do?

The JHipster Native blueprint integrates Spring Native into a JHipster project based on findings from the research by Josh Long and me. I documented our findings in September and December 2021.

Sep 30, 2021: JHipster Works with Spring Native!
Dec 14, 2021: JHipster works with Spring Native, Part 2!

The unexpected thing is, one of the hardest problems we had to solve was with JPA and relationships. In JVM mode, everything worked fine. When running in native mode, there was an exception. The solution took days to figure out, but was quite simple to fix: I just had to add a type hint for java.util.HashSet.class. 🤯

During this experience, I was surprised to find that Spring Native doesn't support caching yet. I believe this support will be added by the community soon. In the meantime, if you're looking to start/stop your infra as fast as possible, you probably don't care about caching. Caching is made for long-lived, JVM-strong, JVM-loving apps.

What's the performance like?

The native binary starts in just over 500ms (577ms) on my 2019 MacBook Pro with a 2.4 GHz 8-Core Intel Core i9 processor and 64 GB of RAM.

If I start it in JVM mode with Maven, it takes a little over four seconds.

As far as build time goes, Spring Native says:

Finished generating 'native-executable' in 3m 15s.

If I build a Docker image with the native binary:

mvn spring-boot:build-image -Pprod

It takes a while the first time:

Total time:  07:24 min

And it's slightly faster the second time:

Total time:  06:43 min

The amount of memory used after starting: 178 MB.

The amount of memory used after running npm run e2e: 211 MB.

In the interest of full disclosure, here's the command I used to measure the amount of memory used:

ps -o pid,rss,command | grep --color native | awk '{$2=int($2/1024)" MB";}{ print;}'

What about the M1 Max? That's not an option yet, but could be in the next release of GraalVM.

Learn more about GraalVM and Spring Native

I hope you've enjoyed learning how to make JHipster work with Spring Native and GraalVM. It's still a work-in-progress. Startup time isn't the end-all-be-all metric, but it is important in a serverless environment.

You can find the source code for this example on GitHub in the @oktadev/auth0-full-stack-java-example repository. The source for the JHipster Native blueprint is in the @jhipster/generator-jhipster-native repository.

JHipster also has Micronaut and Quarkus blueprints. However, their native support is currently a work-in-progress. I hope to help improve them in the next few months.

If you liked this post, there's a good chance you'll like similar ones:

If you have questions, please ask them in the comments below! If you're into social media, follow us: @oktadev on Twitter, Okta for Developers on LinkedIn, and OktaDev on Facebook. If you like learning via video, subscribe to our YouTube channel.

Deploy JHipster Microservices to GCP with Kubernetes

Matt Raible — Wed, 09 Mar 2022 02:03:04 +0000

When your business or application is successful, it needs to scale. Not just technology-wise, but human-wise. When you're growing rapidly, it can be difficult to hire developers fast enough. Using a microservices architecture for your apps can allow you to divide up ownership and responsibilities, and scale teams along with your code.

Kubernetes is an open-source platform for managing containerized workloads and services. Kubernetes traces its lineage directly from Borg, Google's long-rumored internal container-oriented cluster-management system.

Spring Boot and Spring Cloud were some of the pioneering frameworks in Javaland. However, even they stood on the shoulders of giants when they leveraged Netflix's open-source projects to embrace and extend. In 2018, Netflix OSS announced they'd come full circle, and adopted Spring Boot.

Today, I'd like to show you how to build and deploy (with Kubernetes) a reactive microservice architecture with Spring Boot, Spring Cloud, and JHipster. Why reactive? Because Spring Cloud Gateway is now the default for JHipster 7 gateways, even if you choose to build your microservices with Spring MVC.

Spring Cloud Gateway is a library for building an API Gateway on top of Spring WebFlux. It easily integrates with OAuth to communicate between microservices. You just need to add a TokenRelay filter.

spring:
  cloud:
    gateway:
      default-filters:
        - TokenRelay

CAUTION: Spring Cloud no longer supports Netflix Zuul. An open issue adds Spring MVC/Servlet support to Spring Cloud Gateway. It's scheduled for implementation before the end of 2021.

Prerequisites:

You can also watch this tutorial as a screencast.

A Brief Intro to Kubernetes (K8s)

Kubernetes is an open-source project from Google that provides an API for deploying your apps and making them talk with each other. It helps automate deployments and updates, and manages your apps and services with limited downtime. You use Docker containers and YAML to make it all work.

The YAML can be burdensome, but that's where JHipster comes in. It can generate the YAML for you!

Create a Kubernetes-Ready Microservices Architecture

I showed you how to build Reactive Java microservices with Spring Boot and JHipster in a previous post. Today, I'll show you how to generate K8s deployment descriptors, use Spring Cloud Config with Git, encrypt your secrets, and make it all work on Google Cloud (GKE to be specific).

Start by cloning the JHipster 7 { Vue, Spring Boot, WebFlux } reactive microservices project from GitHub:

git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/reactive-jhipster

TIP: If you just want to see the completed project, just cd into the project's jhipster-k8s directory.
cd ../jhipster-k8s

This project has four directories:

gateway: a Spring Boot + Spring Cloud Gateway project configured for OpenID Connect (OIDC) login. It's also configured as an OAuth 2.0 resource server. It contains a front-end application built with Vue.
blog: a Spring Boot + WebFlux microservice that talks to a Neo4j database.
store: a Spring Boot + WebFlux microservice that uses MongoDB.
docker-compose: a set of Docker files that describe how to run all containers together.

NOTE: The SPA app on the gateway is currently a monolith. The JHipster team is still working on micro frontends support.

If you don't have JHipster installed, install it.

npm i -g generator-jhipster@7

Generate Kubernetes Deployment Descriptors

Navigate to the reactive-jhipster directory. Next, create a k8s directory, cd into it, and run JHipster's Kubernetes sub-generator.

mkdir k8s
cd k8s
jhipster k8s

You'll be prompted with several questions. Answer them as I did below:

Type of application: Microservice application
Root directory: ../
Which applications? <select all>
Set up monitoring? No
Which applications with clustered databases? select store
Admin password for JHipster Registry:
Kubernetes namespace: demo
Docker repository name:
Command to push Docker image: docker push
Enable Istio? No
Kubernetes service type? LoadBalancer
Use dynamic storage provisioning? Yes
Use a specific storage class? <leave empty>

NOTE: If you don't want to publish your images on Docker Hub, leave the Docker repository name blank.

After I answered these questions, my k8s/.yo-rc.json file had the following contents:

{
  "generator-jhipster": {
    "appsFolders": ["blog", "gateway", "store"],
    "directoryPath": "../",
    "clusteredDbApps": ["store"],
    "serviceDiscoveryType": "eureka",
    "jwtSecretKey": "NDFhMGY4NjF...",
    "dockerRepositoryName": "mraible",
    "dockerPushCommand": "docker push",
    "kubernetesNamespace": "demo",
    "kubernetesServiceType": "LoadBalancer",
    "kubernetesUseDynamicStorage": true,
    "kubernetesStorageClassName": "",
    "ingressDomain": "",
    "monitoring": "no",
    "istio": false
  }
}

I already showed you how to get everything working with Docker Compose in the previous tutorial. So today, I'd like to show you how to run things locally with Minikube.

Install Minikube to Run Kubernetes Locally

If you have Docker installed, you can run Kubernetes locally with Minikube. Run minikube start to begin.

minikube --cpus 8 start

CAUTION: If this doesn't work, use brew install minikube, or see Minikube's installation instructions.

This command will start Minikube with 16 GB of RAM and 8 CPUs. Unfortunately, the default, which is 16 GB RAM and two CPUs, did not work for me.

You can skip ahead to creating your Docker images while you wait for this to complete.

After this command executes, it'll print out a message and notify you which cluster and namespace are being used.

🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

TIP: You can stop Minikube with minikube stop and start over with minikube delete.

Create Docker Images with Jib

Now, you need to build Docker images for each app. In the { gateway, blog, store } directories, run the following Gradle command (where <image-name> is gateway, store, or blog).

This command should also be in the window where you ran jhipster k8s, so you can copy them from there.

./gradlew bootJar -Pprod jib -Djib.to.image=<docker-repo-name>/<image-name>

Create Private Docker Images

You can also build your images locally and publish them to your Docker daemon. This is the default if you didn't specify a base Docker repository name.

# this command exposes Docker images to minikube
eval $(minikube docker-env)
./gradlew -Pprod bootJar jibDockerBuild

Because this publishes your images locally to Docker, you'll need to make modifications to your Kubernetes deployment files to use imagePullPolicy: IfNotPresent.

- name: gateway-app
  image: gateway
  imagePullPolicy: IfNotPresent

Make sure to add this imagePullPolicy to the following files:

k8s/gateway-k8s/gateway-deployment.yml
k8s/blog-k8s/blog-deployment.yml
k8s/store-k8s/store-deployment.yml

Register an OIDC App for Auth

You've now built Docker images for your microservices, but you haven't seen them running. First, you'll need to configure Okta for authentication and authorization.

JHipster ships with JHipster Registry. It acts as a Eureka service for service discovery and contains a Spring Cloud Config server for distributing your configuration settings.

Update k8s/registry-k8s/application-configmap.yml to contain your OIDC settings from the .okta.env file the Okta CLI just created. The Spring Cloud Config server reads from this file and shares the values with the gateway and microservices.

data:
  application.yml: |-
    ...
    spring:
      security:
        oauth2:
          client:
            provider:
              oidc:
                issuer-uri: https://<your-okta-domain>/oauth2/default
            registration:
              oidc:
                client-id: <client-id>
                client-secret: <client-secret>

To configure the JHipster Registry to use OIDC for authentication, modify k8s/registry-k8s/jhipster-registry.yml to enable the oauth2 profile.

- name: SPRING_PROFILES_ACTIVE
  value: prod,k8s,oauth2

Now that you've configured everything, it's time to see it in action.

Start Your Spring Boot Microservices with K8s

In the k8s directory, start your engines!

./kubectl-apply.sh -f

You can see if everything starts up using the following command.

kubectl get pods -n demo

You can use the name of a pod with kubectl logs to tail its logs.

kubectl logs <pod-name> --tail=-1 -n demo

You can use port-forwarding to see the JHipster Registry.

kubectl port-forward svc/jhipster-registry -n demo 8761

Open a browser and navigate to http://localhost:8761. You'll need to sign in with your Okta credentials.

Once all is green, use port-forwarding to see the gateway app.

kubectl port-forward svc/gateway -n demo 8080

Then, go to http://localhost:8080, and you should be able to add blogs, posts, tags, and products.

You can also automate testing to ensure that everything works. Set your Okta credentials as environment variables and run end-to-end tests using Cypress (from the gateway directory).

export CYPRESS_E2E_USERNAME=<your-username>
export CYPRESS_E2E_PASSWORD=<your-password>
npm run e2e

Proof it worked for me:

Plain Text Secrets? Uggh!

You may notice that I used a secret in plain text in the application-configmap.yml file. Secrets in plain text are a bad practice! I hope you didn't check everything into source control yet!!

Encrypt Your Secrets with Spring Cloud Config

The JHipster Registry has an encryption mechanism you can use to encrypt your secrets. That way, it's safe to store them in public repositories.

Add an ENCRYPT_KEY to the environment variables in k8s/registry-k8s/jhipster-registry.yml.

- name: ENCRYPT_KEY
  value: really-long-string-of-random-charters-that-you-can-keep-safe

TIP: You can use JShell to generate a UUID you can use for your encrypt key.
jshell

UUID.randomUUID()
You can quit by typing /exit.

Restart your JHipster Registry containers from the k8s directory.

./kubectl-apply.sh -f

Encrypt Your OIDC Client Secret

You can encrypt your client secret by logging into http://localhost:8761 and going to Configuration > Encryption. If this address doesn't resolve, you'll need to port-forward again.

kubectl port-forward svc/jhipster-registry -n demo 8761

Copy and paste your client secret from application-configmap.yml (or .okta.env) and click Encrypt.

Then, copy the encrypted value back into application-configmap.yml. Make sure to wrap it in quotes!

You can also use curl:

curl -X POST http://admin:<password-you-set-earlier>@localhost:8761/config/encrypt -d your-client-secret

If you use curl, make sure to add {cipher} to the beginning of the string. For example:

client-secret: "{cipher}1b12934716c32d360c85f651a0793df2777090c..."

Apply these changes and restart all deployments.

./kubectl-apply.sh -f
kubectl rollout restart deploy -n demo

Verify everything still works at http://localhost:8080.

TIP: If you don't want to restart the Spring Cloud Config server when you update its configuration, see Refresh the Configuration in Your Spring Cloud Config Server.

Change Spring Cloud Config to use Git

You might want to store your app's configuration externally. That way, you don't have to redeploy everything to change values. Good news! Spring Cloud Config makes it easy to switch to Git instead of the filesystem to store your configuration.

In k8s/registry-k8s/jhipster-registry.yml, find the following variables:

- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_TYPE
  value: native
- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_SEARCH_LOCATIONS
  value: file:./central-config

Below these values, add a second lookup location.

- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_1_TYPE
  value: git
- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_1_URI
  value: https://github.com/mraible/reactive-java-ms-config/
- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_1_SEARCH_PATHS
  value: config
- name: SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_1_LABEL
  value: main

Create a GitHub repo that matches the URI, path, and branch you entered.

In my case, I created reactive-java-ms-config and added a config/application.yml file in the main branch. Then, I added my spring.security.* values to it and removed them from k8s/registry-k8s/application-configmap.yml.

See Spring Cloud Config's Git Backend docs for more information.

Deploy Spring Boot Microservices to Google Cloud (aka GCP)

It's nice to see things running locally on your machine, but it's even better to get to production! In this section, I'll show you how to deploy your containers to Google Cloud.

First, stop Minikube if you were running it previously.

minikube stop

You can also use kubectl commands to switch clusters.

kubectl config get-contexts
kubectl config use-context XXX

The cool kids use kubectx and kubens to set the default context and namespace. You can learn how to install and use them via the kubectx GitHub project.

Create a Container Registry on Google Cloud

Before the JHipster 7.0.0 release, I tested this microservice example with Kubernetes and Google Cloud. I found many solutions in Ray Tsang's Spring Boot on GCP Guides. Thanks, Ray!

To start with Google Cloud, you'll need an account and a project. Sign up for Google Cloud Platform (GCP), log in, and create a project. Open a console in your browser. A GCP project contains all cloud services and resources--such as virtual machines, network, load balancers--that you might use.

TIP: You can also download and install the gcloud CLI if you want to run things locally.

Enable the Google Kubernetes Engine API and Container Registry:

gcloud services enable container.googleapis.com containerregistry.googleapis.com

Create a Kubernetes Cluster

Run the following command to create a cluster for your apps.

gcloud container clusters create CLUSTER_NAME \
--zone us-central1-a \
--machine-type n1-standard-4 \
--enable-autorepair \
--enable-autoupgrade

I called my cluster reactive-ms. See GCP's zones and machine-types for other options. I found the n1-standard-4 to be the minimum for JHipster.

You created Docker images earlier to run with Minikube. Then, those images were deployed to Docker Hub or your local Docker registry. If you deployed to Docker Hub, you can use your deployment files as-is.

For Google Cloud and its Kubernetes engine (GKE), you can also publish your images to your project's registry. Thankfully, this is easy to do with Jib.

Navigate to the gateway directory and run:

./gradlew bootJar -Pprod jib -Djib.to.image=gcr.io/<your-project-id>/gateway

You can get your project ID by running gcloud projects list.

Repeat the process for blog and store. You can run these processes in parallel to speed things up.

cd ../blog
./gradlew bootJar -Pprod jib -Djib.to.image=gcr.io/<your-project-id>/blog
cd ../store
./gradlew bootJar -Pprod jib -Djib.to.image=gcr.io/<your-project-id>/store

TIP: You might have to run gcloud auth configure-docker for Jib to publish to your GCP container registry.

Then, in your k8s/**/*-deployment.yml files, add gcr.io/<your-project-id> as a prefix. Remove the imagePullPolicy if you specified it earlier. For example:

containers:
  - name: gateway-app
    image: gcr.io/jhipster7/gateway
    env:

In the k8s directory, apply all the deployment descriptors to run all your images.

./kubectl-apply.sh -f

You can monitor the progress of your deployments with kubectl get pods -n demo.

TIP: If you make a mistake configuring JHipster Registry and need to deploy it, you can do so with the following command:
kubectl apply -f registry-k8s/jhipster-registry.yml -n demo
kubectl rollout restart statefulset/jhipster-registry -n demo
You'll need to restart all your deployments if you changed any configuration settings that services need to retrieve.
kubectl rollout restart deploy -n demo

Access Your Gateway on Google Cloud

Once everything is up and running, get the external IP of your gateway.

kubectl get svc gateway -n demo

You'll need to add the external IP address as a valid redirect to your Okta OIDC app. Run okta login, open the returned URL in your browser, and sign in to the Okta Admin Console. Go to the Applications section, find your application, and edit it.

Add the standard JHipster redirect URIs using the IP address. For example, http://34.71.48.244:8080/login/oauth2/code/oidc for the login redirect URI, and http://34.71.48.244:8080 for the logout redirect URI.

You can use the following command to set your gateway's IP address as a variable you can curl.

EXTERNAL_IP=$(kubectl get svc gateway -ojsonpath="{.status.loadBalancer.ingress[0].ip}" -n demo)
curl $EXTERNAL_IP:8080

Run open http://$EXTERNAL_IP:8080, and you should be able to sign in.

Great! Now that you know things work, let's integrate better security, starting with HTTPS.

Add HTTPS to Your Reactive Gateway

You should always use HTTPS. It's one of the easiest ways to secure things, especially with the free certificates offered these days. Ray Tsang's External Load Balancing docs was a big help in figuring out all these steps.

You'll need a static IP to assign your TLS (the official name for HTTPS) certificate.

gcloud compute addresses create gateway-ingress-ip --global

You can run the following command to make sure it worked.

gcloud compute addresses describe gateway-ingress-ip --global --format='value(address)'

Then, create a k8s/ingress.yml file:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: gateway
  annotations:
    kubernetes.io/ingress.global-static-ip-name: "gateway-ingress-ip"
spec:
  rules:
    - http:
        paths:
          - path: /*
            pathType: ImplementationSpecific
            backend:
              service:
                name: gateway
                port:
                  number: 8080

Deploy it and make sure it worked.

kubectl apply -f ingress.yml -n demo

# keep running this command displays an IP address
# (hint: up arrow recalls the last command)
kubectl get ingress gateway -n demo

To use a TLS certificate, you must have a fully qualified domain name and configure it to point to the IP address. If you don't have a real domain, you can use nip.io.

Set the IP in a variable, as well as the domain.

EXTERNAL_IP=$(kubectl get ingress gateway -ojsonpath="{.status.loadBalancer.ingress[0].ip}" -n demo)
DOMAIN="${EXTERNAL_IP}.nip.io"

# Prove it works
echo $DOMAIN
curl $DOMAIN

To create a certificate, create a k8s/certificate.yml file.

cat << EOF > certificate.yml
apiVersion: networking.gke.io/v1
kind: ManagedCertificate
metadata:
  name: gateway-certificate
spec:
  domains:
  # Replace the value with your domain name
  - ${DOMAIN}
EOF

Add the certificate to ingress.yml:

...
metadata:
  name: gateway
  annotations:
    kubernetes.io/ingress.global-static-ip-name: "gateway-ingress-ip"
    networking.gke.io/managed-certificates: "gateway-certificate"
...

Deploy both files:

kubectl apply -f certificate.yml -f ingress.yml -n demo

Check your certificate's status until it prints Status: ACTIVE:

kubectl describe managedcertificate gateway-certificate -n demo

While you're waiting, you can proceed to forcing HTTPS in the next step.

Force HTTPS with Spring Security

Spring Security's WebFlux support makes it easy to redirect to HTTPS. However, if you redirect all HTTPS requests, the Kubernetes health checks will fail because they receive a 302 instead of a 200.

Crack open SecurityConfiguration.java in the gateway project and add the following code to the springSecurityFilterChain() method.

http.redirectToHttps(redirect -> redirect
    .httpsRedirectWhen(e -> e.getRequest().getHeaders().containsKey("X-Forwarded-Proto"))
);

Rebuild the Docker image for the gateway project.

./gradlew bootJar -Pprod jib -Djib.to.image=gcr.io/<your-project-id>/gateway

Run the following commands to start a rolling restart of gateway instances:

kubectl rollout restart deployment gateway -n demo

TIP: Run kubectl get deployments to see your deployment names.

Now you should get a 302 when you access your domain. HTTPie is a useful alternative to curl.

Update your Okta OIDC app to have https://${DOMAIN}/login/oauth2/code/oidc as a valid redirect URI. Add https://${DOMAIN} to the sign-out redirect URIs too.

Encrypt Your Kubernetes Secrets

Congratulations! Now you have everything running on GKE, using HTTPS! However, you have a lot of plain-text secrets in your K8s YAML files.

"But, wait!" you might say. Doesn't Kubernetes Secrets solve everything?

In my opinion, no. They're just unencrypted base64-encoded strings stored in YAML files. There's a good chance you'll want to check in the k8s directory you created.

Having secrets in your source code is a bad idea! The good news is most people (where most people = my followers) manage secrets externally.

// Detect dark theme var iframe = document.getElementById('tweet-1387439868444397568-901'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1387439868444397568&theme=dark" }

NOTE: Watch Kubernetes Secrets in 5 Minutes if you want to learn more about Kubernetes Secrets.

The Current State of Secret Management in Kubernetes

I recently noticed a tweet from Daniel Jacob Bilar that links to a talk from FOSDEM 2021 on the current state of secret management within Kubernetes. It's an excellent overview of the various options.

Store Secrets in Git with Sealed Secrets and Kubeseal

Bitnami has a Sealed Secrets Apache-licensed open source project. Its README explains how it works.

Problem: "I can manage all my K8s config in git, except Secrets."

Solution: Encrypt your Secret into a SealedSecret, which is safe to store - even to a public repository. The SealedSecret can be decrypted only by the controller running in the target cluster, and nobody else (not even the original author) is able to obtain the original Secret from the SealedSecret.

Store your Kubernetes Secrets in Git thanks to Kubeseal. Hello SealedSecret! by Aurélie Vache provides an excellent overview of how to use it.

First, you'll need to install the Sealed Secrets CRD (Custom Resource Definition).

kubectl apply -f https://github.com/bitnami-labs/sealed-secrets/releases/download/v0.16.0/controller.yaml

Retrieve the certificate keypair that this controller generates.

kubectl get secret -n kube-system -l sealedsecrets.bitnami.com/sealed-secrets-key -o yaml

Copy the raw value of tls.crt and decode it. You can use the command line, or learn more about base64 encoding/decoding in our documentation.

echo -n <paste-value-here> | base64 --decode

Put the raw value in a tls.crt file.

Next, install Kubeseal. On macOS, you can use Homebrew. For other platforms, see the release notes.

brew install kubeseal

The major item you need to encrypt in this example is the ENCRYPT_KEY you used to encrypt the OIDC client secret. Run the following command to do this, where the value comes from your k8s/registry-k8s/jhipster-registry.yml file.

kubectl create secret generic encrypt-key \
  --from-literal=ENCRYPT_KEY='your-value-here' \
  --dry-run=client -o yaml > secrets.yml

Next, use kubeseal to convert the secrets to encrypted secrets.

kubeseal --cert tls.crt --format=yaml -n demo < secrets.yml > sealed-secrets.yml

Remove the original secrets file and deploy your sealed secrets.

rm secrets.yml
kubectl apply -n demo -f sealed-secrets.yml && kubectl get -n demo sealedsecret encrypt-key

Configure JHipster Registry to use the Sealed Secret

In k8s/registry-k8s/jhipster-registry.yml, change the ENCRYPT_KEY to use your new secret.

...
- name: ENCRYPT_KEY
  valueFrom:
    secretKeyRef:
      name: encrypt-key
      key: ENCRYPT_KEY

TIP: You should be able to encrypt other secrets, like your database passwords, using a similar technique.

Now, redeploy JHipster Registry and restart all your deployments.

./kubectl-apply.sh -f
kubectl rollout restart deployment -n demo

You can use port-forwarding to see the JHipster Registry locally.

kubectl port-forward svc/jhipster-registry -n demo 8761

Google Cloud Secret Manager

Google Cloud has a Secret Manager you can use to store your secrets. There's even a Spring Boot starter to make it convenient to retrieve these values in your app.

For example, you could store your database password in a properties file.

spring.datasource.password=${sm://my-db-password}

This is pretty slick, but I like to remain cloud-agnostic. Also, I like how the JHipster Registry allows me to store encrypted secrets in Git.

Use Spring Vault for External Secrets

Using an external key management solution like HashiCorp Vault is also recommended. The JHipster Registry will have Vault support in its next release.

In the meantime, I recommend reading Secure Secrets With Spring Cloud Config and Vault.

Scale Your Reactive Java Microservices

You can scale your instances using the kubectl scale command.

kubectl scale deployments/store --replicas=2 -n demo

Scaling will work just fine for the microservice apps because they're set up as OAuth 2.0 resource servers and are therefore stateless.

However, the gateway uses Spring Security's OIDC login feature and stores the access tokens in the session. So if you scale it, sessions won't be shared. Single sign-on should still work; you'll just have to do the OAuth dance to get tokens if you hit a different instance.

To synchronize sessions, you can use Spring Session and Redis with JHipster.

CAUTION: If you leave everything running on Google Cloud, you will be charged for usage. Therefore, I recommend removing your cluster or deleting your namespace (kubectl delete ns demo) to reduce your cost.
gcloud container clusters delete <cluster-name> --zone=us-central1-a
You can delete your Ingress IP address too:
gcloud compute addresses delete gateway-ingress-ip --global

Monitor Your Kubernetes Cluster with K9s

Using kubectl to monitor your Kubernetes cluster can get tiresome. That's where K9s can be helpful. It provides a terminal UI to interact with your Kubernetes clusters. K9s was created by my good friend Fernand Galiana. He's also created a commercial version called K9sAlpha.

To install it on macOS, run brew install k9s. Then run k9s -n demo to start it. You can navigate to your pods, select them with Return, and navigate back up with Esc.

There's also KDash, from JHipster co-lead, Deepu K Sasidharan. It's a simple K8s terminal dashboard built with Rust. Deepu recently released an MVP of the project.

If for some reason you don't like CLI's, you can try Kubernetic.

Continuous Integration and Delivery of JHipster Microservices

This tutorial doesn't mention continuous integration and delivery of your reactive microservice architecture. I plan to cover that in a future post. If you have a solution you like, please leave a comment.

Spring on Google Cloud Platform

JHipster uses Docker containers to run all its databases in this example. However, there are a number of Google Cloud services you can use as alternatives. See the Spring Cloud GCP project on GitHub for more information.

I didn't mention Testcontainers in this post. However, JHipster does support using them. Testcontainers also has a GCloud Module.

Why Not Istio?

I didn't use Istio in this example because I didn't want to complicate things. Learning Kubernetes is hard enough without learning another system on top of it. Istio acts as a network between your containers that can do networky things like authentication, authorization, monitoring, and retries. I like to think of it as AOP for containers.

If you'd like to see how to use JHipster with Istio, see How to set up Java microservices with Istio service mesh on Kubernetes by JHipster co-lead Deepu K Sasidharan.

Fernand Galiana recommends checking out BPF (Berkeley Packet Filter) and Cilium. Cilium is open source software for transparently providing and securing the network and API connectivity between application services deployed using Linux container management platforms such as Kubernetes.

Learn More About Kubernetes, Spring Boot, and JHipster

This blog post showed you how to deploy your reactive Java microservices to production using Kubernetes. JHipster did much of the heavy lifting for you since it generated all the YAML-based deployment descriptors. Since no one really likes writing YAML, I'm calling that a win!

You learned how to use JHipster Registry to encrypt your secrets and configure Git as a configuration source for Spring Cloud Config. Bitnami's Sealed Secrets is a nice companion to encrypt the secrets in your Kubernetes deployment descriptors.

For more information about storing your secrets externally, these additional resources might help.

You can find the source code for this example on GitHub in our Java microservices examples repository.

git clone https://github.com/oktadev/java-microservices-examples.git
cd java-microservices-examples/jhipster-k8s

See JHipster's documentation on Kubernetes and GCP if you'd like more concise instructions.

If you enjoyed this post, I think you'll like these others as well:

If you have any questions, please ask them in the comments below.

To be notified when we publish new blog posts, follow us on Twitter or LinkedIn. We frequently publish videos to our YouTube channel too. Subscribe today!

A huge thanks goes to Fernand Galiana for his review and detailed feedback.

The Angular Mini-Book 2.0 is now available!

Matt Raible — Wed, 02 Mar 2022 18:28:21 +0000

I'm pumped to announce that the Angular Mini-Book 2.0 has been released! You can download it in PDF and EPUB formats from InfoQ.

About this book

The Angular Mini-Book is a guide to getting started with Angular. You'll learn how to develop a bare-bones application, test it, and deploy it. Then you'll move on to adding Bootstrap, Angular Material, continuous integration, and authentication.

Spring Boot is a popular framework for building REST APIs. You'll learn how to integrate Angular with Spring Boot and use security best practices like HTTPS and a content security policy. What about deploying your Angular app to the cloud? Yep, it covers that too!

What's new?

This new edition (2.0) uses Angular 13 and Spring Boot 2.6. Some other fun facts:

First commit on 2.0 version: Nov 19, 2021 { Thanks to James Ward for his help upgrading to Knative 1.0! }
Upgraded the book's project to use Gradle 7: Dec 2, 2021 { I appreciate you Guillaume Grossetie! }
Upgraded to Angular 13 and Spring Boot 2.6.1: Jan 7, 2022
Detailed QA of all the code: Jan 27 - Feb 10, 2022
Files changed since 1.0: 244
Build date: Feb 17, 2022

For more information about this book, please read my post about its 1.0 release.

To send us feedback or issues, e-mail InfoQ at feedback@infoq.com, email me at matt@raibledesigns.com, or hit me up on Twitter @mraible.

Java Microservices with Spring Cloud Config and JHipster

Matt Raible — Thu, 23 May 2019 05:00:00 +0000

Developing a microservice architecture with Java and Spring Boot is quite popular these days. It’s definitely one of the most popular combinations in the Java ecosystem. If you need any proof, just look at all of the similar frameworks that have cropped up in the last few years: MicroProfile, Micronaut, and Quarkus, just to name a few.

Spring Boot provided a much-needed spark to the Spring ecosystem when it was first released in 2014. Instead of making Java developers configure all aspects of their Spring beans, it provided "starters" that contained pre-configured beans with the default settings. This led to less Java code, and also provided the ability to override the defaults via an application.properties file. Yes, there are many ways to modify the defaults in a Spring Boot application, but I’ll skip over that for now.

In a previous tutorial on Java Microservices with Spring Boot and Spring Cloud, I showed how you can use OAuth 2.0 and OpenID Connect to secure everything. One of the problems with this example is that you have to configure the OIDC properties in each application. This can be a real pain if you have hundreds of microservices. Yes, you could define them as environment variables and this would solve the problem. However, if you have different microservices stacks using different OIDC client IDs, this approach will be difficult.

Java Microservices with Spring Cloud Config

Spring Cloud Config is a project that provides externalized configuration for distributed systems. Spring Cloud Config has server and client components. You can configure the server to read its configuration from the file system or a source code repository, like Git. On the client, you configure things in a bootstrap configuration file to get configuration data from the server. In a microservices environment, this provides an elegant way to configure all your microservices from a central location.

Today I’d like to show you how this works and demo it using one of the hippest microservice solutions I’ve ever worked with.

Use JHipster to Generate a Java Microservices Architecture

JHipster is a development platform to generate, develop, and deploy Spring Boot + { Angular or React or Vue } applications. In addition, it supports creating Spring-based microservice architectures. In fact, if you create microservices projects and choose OAuth 2.0 / OIDC for authentication, you’ll be using code that’s very similar to the aforementioned example.

To use JHipster, you’ll need to have Node.js installed. You can also use start.jhipster.tech, which is similar to start.spring.io.

The most common way to install JHipster is using npm:



npm install -g generator-jhipster@6.0.1

NOTE: You can run the command above without the version number to get the latest version of JHipster. If it’s 6.x, this tutorial should work, but I can’t guarantee it does.

In a terminal, create a directory to hold all the projects you’re about to create. For example, jhipster.

Create an apps.jh file in this directory and put the following code into it.



application {
  config {
    baseName gateway,
    packageName com.okta.developer.gateway,
    applicationType gateway,
    authenticationType oauth2,
    prodDatabaseType postgresql,
    serviceDiscoveryType eureka,
    testFrameworks [protractor]
  }
  entities Blog, Post, Tag, Product
}

application {
  config {
    baseName blog,
    packageName com.okta.developer.blog,
    applicationType microservice,
    authenticationType oauth2,
    prodDatabaseType postgresql,
    serverPort 8081,
    serviceDiscoveryType eureka
  }
  entities Blog, Post, Tag
}

application {
  config {
    baseName store,
    packageName com.okta.developer.store,
    applicationType microservice,
    authenticationType oauth2,
    databaseType mongodb,
    devDatabaseType mongodb,
    prodDatabaseType mongodb,
    enableHibernateCache false,
    serverPort 8082,
    serviceDiscoveryType eureka
  }
  entities Product
}

entity Blog {
  name String required minlength(3),
  handle String required minlength(2)
}

entity Post {
  title String required,
  content TextBlob required,
  date Instant required
}

entity Tag {
  name String required minlength(2)
}

entity Product {
  title String required,
  price BigDecimal required min(0),
  image ImageBlob
}

relationship ManyToOne {
  Blog{user(login)} to User,
  Post{blog(name)} to Blog
}

relationship ManyToMany {
  Post{tag(name)} to Tag{post}
}

paginate Post, Tag with infinite-scroll
paginate Product with pagination

microservice Product with store
microservice Blog, Post, Tag with blog

// will be created under 'docker-compose' folder
deployment {
  deploymentType docker-compose
  appsFolders [gateway, blog, store]
  dockerRepositoryName "jmicro"
  consoleOptions [zipkin]
}

TIP: You’ll want to change the dockerRepositoryName in the JDL above to use your Docker Hub username if you want to publish your containers. This is not a necessary step to complete this tutorial.

This code is JDL (JHipster Domain Language) and you can use it to define your app, its entities, and even deployment settings. You can learn more about JDL in JHipster’s JDL documentation. Below is a screenshot of JDL Studio, which can be used to edit JDL and see how entities related to each other.

The JDL you just put in apps.jh defines three applications:

gateway: a single entry point to your microservices, that will include the UI components.
blog: a blog service that talks to PostgreSQL.
store: a store service that uses MongoDB.

Run the following command to create these projects in your jhipster folder.



jhipster import-jdl apps.jh

This will create all three projects in parallel.

Create Docker Images for Microservice Apps

When the configuration is generated for Docker Compose, a warning is spat out to the console.



WARNING! Docker Compose configuration generated, but no Jib cache found
If you forgot to generate the Docker image for this application, please run:
To generate the missing Docker image(s), please run:
  ./mvnw -Pprod verify jib:dockerBuild in /Users/mraible/java-microservices-examples/jhipster/gateway
  ./mvnw -Pprod verify jib:dockerBuild in /Users/mraible/java-microservices-examples/jhipster/blog
  ./mvnw -Pprod verify jib:dockerBuild in /Users/mraible/java-microservices-examples/jhipster/store

To make it easier to create Docker images with one command, create an aggregator pom.xml in the jhipster root directory.



<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.okta.developer</groupId>
    <artifactId>jhipster-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <name>jhipster-parent</name>
    <modules>
        <module>gateway</module>
        <module>blog</module>
        <module>store</module>
    </modules>
</project>

Then "just jib it" using Jib.



mvn -Pprod verify com.google.cloud.tools:jib-maven-plugin:dockerBuild

TIP: If you don’t have Maven installed, use brew install maven on a Mac, or see Maven’s installation docs.



[INFO] Skipping containerization because packaging is 'pom'...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] Gateway 0.0.1-SNAPSHOT ............................. SUCCESS [02:44 min]
[INFO] Blog 0.0.1-SNAPSHOT ................................ SUCCESS [ 34.391 s]
[INFO] Store 0.0.1-SNAPSHOT ............................... SUCCESS [ 28.589 s]
[INFO] jhipster-parent 1.0.0-SNAPSHOT ..................... SUCCESS [  1.096 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 03:49 min
[INFO] Finished at: 2019-05-17T07:44:39-06:00
[INFO] ------------------------------------------------------------------------
Execution time: 3 min. 50 s.

Run Your Java Microservices Stack with Docker Compose

Once everything has finished building, cd into the docker-compose directory and start all your containers.



cd docker-compose
docker-compose up -d

TIP: Remove the -d if you want to see all the logs in your current terminal window.

It will take several minutes to start all eight of your containers. You can use Kitematic to monitor their startup progress if you like.



Creating docker-compose_gateway-app_1 ... done
Creating docker-compose_gateway-postgresql_1 ... done
Creating docker-compose_blog-app_1 ... done
Creating docker-compose_store-mongodb_1 ... done
Creating docker-compose_keycloak_1 ... done
Creating docker-compose_blog-postgresql_1 ... done
Creating docker-compose_jhipster-registry_1 ... done
Creating docker-compose_store-app_1 ... done

JHipster Registry for Service Discovery with Java Microservices

This microservices stack uses Eureka for service discovery, just like the bare-bones Spring Boot + Spring Cloud example. This was determined by the following line for each app in the JDL.



serviceDiscoveryType eureka

When you select eureka for service discovery, JHipster Registry is used. This application is very similar to Eureka Server, except it has an Angular UI and includes Spring Cloud Config, among other features.

TIP: JHipster also supports Hashicorp Consul for service discovery.

Because you chose OAuth 2.0/OIDC for authentication, you’ll need to create an entry in your hosts file (/etc/hosts on Linux/Mac, C:\Windows\System32\Drivers\etc\hosts on Windows) for Keycloak.



127.0.0.1 keycloak

This is because the Docker network recognizes keycloak as a registered hostname, but it also redirects you to keycloak. Your browser is not aware of that hostname without the hosts entry.

Open your browser and navigate to http://localhost:8761. You’ll be redirected to Keycloak to login. Enter admin/admin for credentials and you’ll be redirected back to JHipster Registry. You’ll see all your microservice instances have been registered.

Navigate to http://localhost:8080, click sign in, and you’ll be logged in to the gateway. You can go to Entities > Blog and add a blog.

Go to Entities > Product and you can add a product too.

Pretty slick, don’t you think?! 🤓

Configure JHipster Microservices to Use Okta for Identity

One of the problems you saw in the bare-bones Spring Boot + Spring Cloud setup is you have to configure okta.oauth2.* properties in every microservice. JHipster doesn’t use the Okta Spring Boot starter. It uses oauth2-client and oauth2-resource-server Spring Boot starters instead. The configuration for OAuth 2.0 is contained in each app’s src/main/resources/config/application.yml file.



spring:
  ...
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: http://localhost:9080/auth/realms/jhipster
        registration:
          oidc:
            client-id: internal
            client-secret: internal

Why Okta?

You might be wondering why you should use Okta instead of Keycloak? Keycloak works great for development and testing, and especially well if you’re on a plane with no wi-fi. However, in production, you want a system that’s always on. That’s where Okta comes in. To begin, you’ll need to create an Okta account and an application with it.

Create a Web Application in Okta

From the Applications page, choose Add Application.
On the Create New Application page, select Web.
Give your app a memorable name, add http://localhost:8080/login/oauth2/code/okta as a Login redirect URI, select Refresh Token (in addition to Authorization Code ), and click Done.
To configure Logout to work in JHipster, Edit your app, add http://localhost:8080 as a Logout redirect URI, then click Save.

Configure Your OpenID Connect Settings with Spring Cloud Config

Rather than modifying each of your apps for Okta, you can use Spring Cloud Config in JHipster Registry to do it. Open docker-compose/central-server-config/application.yml and add your Okta settings.

The client ID and secret are available on your app settings page. You can find the issuer under API > Authorization Servers.



spring:
  security:
    oauth2:
      client:
        provider:
          oidc:
            issuer-uri: https://{yourOktaDomain}/oauth2/default
        registration:
          oidc:
            client-id: {yourClientId}
            client-secret: {yourClientSecret}

The registry, gateway, blog, and store applications are all configured to read this configuration on startup.

Restart all your containers for this configuration to take effect.



docker-compose restart

Before you can log in, you’ll need to add redirect URIs for JHipster Registry, ensure your user is in a ROLE_ADMIN group and that groups are included in the ID token.

http://localhost:8761/login/oauth2/code/oidc

You’ll also need to add a Logout redirect URI:

http://localhost:8761

Then, click Save.

Create Groups and Add Them as Claims to the ID Token

JHipster is configured by default to work with two types of users: administrators and users. Keycloak is configured with users and groups automatically, but you need to do some one-time configuration for your Okta organization.

Create a ROLE_ADMIN group ( Users > Groups > Add Group ) and add your user to it. Navigate to API > Authorization Servers , and click on the the default server. Click the Claims tab and Add Claim. Name it groups, and include it in the ID Token. Set the value type to Groups and set the filter to be a Regex of .*. Click Create.

Now when you hit http://localhost:8761 or http://localhost:8080, you’ll be prompted to log in with Okta!

It’s pretty nifty how you can configure your service registry and all your microservices in one place with Spring Cloud Config, don’t you think?! 👌

Configuring Spring Cloud Config with Git

JHipster Registry and its Spring Cloud Config server support two kinds of configuration sources: native and git. Which one is used is determined by a spring.cloud.config.server.composite property. If you look in docker-compose/jhipster-registry.yml, you’ll see that native is enabled and git is commented out.



- SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_TYPE=native
- SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_SEARCH_LOCATIONS=file:./central-config
# - SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_TYPE=git
# - SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_URI=https://github.com/jhipster/jhipster-registry/
# - SPRING_CLOUD_CONFIG_SERVER_COMPOSITE_0_SEARCH_PATHS=central-config
# For Keycloak to work, you need to add '127.0.0.1 keycloak' to your hosts file

You can see the default configuration for Git at @jhipster/jhipster-registry/central-config/application.yml. You can learn more about application configuration with Spring Cloud Config in JHipster Registry’s documentation. It includes a section on encrypting configuration values.

What About Kotlin Microservices?

In the first post of this series, I told you why I wrote this post in Java:

"I wrote this post with Java because it’s the most popular language in the Java ecosystem. However, Kotlin is on the rise, according to RedMonk’s programming language rankings from January 2019."

Spring has excellent support for Kotlin, and you can choose it as a language on start.spring.io. JHipster has support for Kotlin too with its Kotlin Blueprint! A new release was published last week that allows you to create Kotlin-based JHipster apps with khipster.

If you’d like to see us write more posts using Kotlin, please let us know in the comments!

Learn More about Spring Cloud Config, Java Microservices, and JHipster

I hope you enjoyed learning how to build Java microservice architectures with JHipster and configure them with Spring Cloud Config. You learned how to generate everything from a single JDL file, package your apps in Docker containers, run them with Docker Compose, and authenticate with OIDC using Keycloak and Okta.

You can find all the code shown in this tutorial on GitHub in the jhipster directory.

We’re big fans of Spring Boot, Spring Cloud, and JHipster on this blog. Here are a few other posts you might find interesting:

Please follow us on Twitter @oktadev and subscribe to our YouTube channel for more Spring and Spring Security tips.

Java Microservices with Spring Boot and Spring Cloud

Matt Raible — Wed, 22 May 2019 05:00:00 +0000

Java is a great language to use when developing a microservice architecture. In fact, some of the biggest names in our industry use it. Have you ever heard of Netflix, Amazon, or Google? What about eBay, Twitter, and LinkedIn? Yes, major companies handling incredible traffic are doing it with Java.

Implementing a microservices architecture in Java isn’t for everyone. For that matter, implementing microservices, in general, isn’t often needed. Most companies do it to scale their people, not their systems. If you’re going to scale your people, hiring Java developers is one of the best ways to do it. After all, there are more developers fluent in Java than most other languages - though JavaScript seems to be catching up quickly!

The Java ecosystem has some well-established patterns for developing microservice architectures. If you’re familiar with Spring, you’ll feel right at home developing with Spring Boot and Spring Cloud. Since that’s one of the quickest ways to get started, I figured I’d walk you through a quick tutorial.

Create Java Microservices with Spring Cloud and Spring Boot

In most of my tutorials, I show you how to build everything from scratch. Today I’d like to take a different approach and step through a pre-built example with you. Hopefully, this will be a bit shorter and easier to understand.

You can start by cloning the @oktadeveloper/java-microservices-examples repository.

git clone https://github.com/oktadeveloper/java-microservices-examples.git
cd java-microservices-examples/spring-boot+cloud

In the spring-boot+cloud directory, there are three projects:

discovery-service: a Netflix Eureka server, used for service discovery.
car-service: a simple Car Service that uses Spring Data REST to serve up a REST API of cars.
api-gateway: an API gateway that has a /cool-cars endpoint that talks to the car-service and filters out cars that aren’t cool (in my opinion, of course).

I created all of these applications using start.spring.io’s REST API and HTTPie.

http https://start.spring.io/starter.zip javaVersion==11 \
  artifactId==discovery-service name==eureka-service \
  dependencies==cloud-eureka-server baseDir==discovery-service | tar -xzvf -

http https://start.spring.io/starter.zip \
  artifactId==car-service name==car-service baseDir==car-service \
  dependencies==actuator,cloud-eureka,data-jpa,h2,data-rest,web,devtools,lombok | tar -xzvf -

http https://start.spring.io/starter.zip \
  artifactId==api-gateway name==api-gateway baseDir==api-gateway \
  dependencies==cloud-eureka,cloud-feign,data-rest,web,cloud-hystrix,lombok | tar -xzvf -

Spring Microservices with Java 11+

To make the discovery-service run on Java 11, I had to add a dependency on JAXB.

<dependency>
    <groupId>org.glassfish.jaxb</groupId>
    <artifactId>jaxb-runtime</artifactId>
</dependency>

The other two applications worked fine out-of-the-box on Java 11 with no changes in dependencies.

Java Service Discovery with Netflix Eureka

The discovery-service is configured the same as you would most Eureka servers. It as an @EnableEurekaServer annotation on its main class and properties that set its port and turn off discovery.

server.port=8761
eureka.client.register-with-eureka=false

The car-service and api-gateway projects are configured in a similar fashion. Both have a unique name defined and car-service is configured to run on port 8090 so it doesn’t conflict with 8080.

car-service/src/main/resources/application.properties

server.port=8090
spring.application.name=car-service

api-gateway/src/main/resources/application.properties

spring.application.name=api-gateway

The main class in both projects is annotated with @EnableDiscoveryClient.

Build a Java Microservice with Spring Data REST

The car-service provides a REST API that lets you CRUD (Create, Read, Update, and Delete) cars. It creates a default set of cars when the application loads using an ApplicationRunner bean.

car-service/src/main/java/com/example/carservice/CarServiceApplication.java

package com.example.carservice;

import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.NonNull;
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.context.annotation.Bean;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import java.util.stream.Stream;

@EnableDiscoveryClient
@SpringBootApplication
public class CarServiceApplication {

    public static void main(String[] args) {
        SpringApplication.run(CarServiceApplication.class, args);
    }

    @Bean
    ApplicationRunner init(CarRepository repository) {
        return args -> {
            Stream.of("Ferrari", "Jaguar", "Porsche", "Lamborghini", "Bugatti",
                    "AMC Gremlin", "Triumph Stag", "Ford Pinto", "Yugo GV").forEach(name -> {
                repository.save(new Car(name));
            });
            repository.findAll().forEach(System.out::println);
        };
    }
}

@Data
@NoArgsConstructor
@Entity
class Car {

    public Car(String name) {
        this.name = name;
    }

    @Id
    @GeneratedValue
    private Long id;

    @NonNull
    private String name;
}

@RepositoryRestResource
interface CarRepository extends JpaRepository<Car, Long> {
}

Spring Cloud + Feign and Hystrix in an API Gateway

Feign makes writing Java HTTP clients easier. Spring Cloud makes it possible to create a Feign client with just a few lines of code. Hystrix makes it possible to add failover capabilities to your Feign clients so they’re more resilient.

The api-gateway uses Feign and Hystrix to talk to the downstream car-service and failover to a fallback() method if it’s unavailable. It also exposes a /cool-cars endpoint that filters out cars you might not want to own.

api-gateway/src/main/java/com/example/apigateway/ApiGatewayApplication.java

package com.example.apigateway;

import com.netflix.hystrix.contrib.javanica.annotation.HystrixCommand;
import lombok.Data;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.circuitbreaker.EnableCircuitBreaker;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
import org.springframework.cloud.netflix.zuul.EnableZuulProxy;
import org.springframework.cloud.openfeign.EnableFeignClients;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.hateoas.Resources;
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.ArrayList;
import java.util.Collection;
import java.util.stream.Collectors;

@EnableFeignClients
@EnableCircuitBreaker
@EnableDiscoveryClient
@EnableZuulProxy
@SpringBootApplication
public class ApiGatewayApplication {

    public static void main(String[] args) {
        SpringApplication.run(ApiGatewayApplication.class, args);
    }
}

@Data
class Car {
    private String name;
}

@FeignClient("car-service")
interface CarClient {

    @GetMapping("/cars")
    @CrossOrigin
    Resources<Car> readCars();
}

@RestController
class CoolCarController {

    private final CarClient carClient;

    public CoolCarController(CarClient carClient) {
        this.carClient = carClient;
    }

    private Collection<Car> fallback() {
        return new ArrayList<>();
    }

    @GetMapping("/cool-cars")
    @CrossOrigin
    @HystrixCommand(fallbackMethod = "fallback")
    public Collection<Car> goodCars() {
        return carClient.readCars()
                .getContent()
                .stream()
                .filter(this::isCool)
                .collect(Collectors.toList());
    }

    private boolean isCool(Car car) {
        return !car.getName().equals("AMC Gremlin") &&
                !car.getName().equals("Triumph Stag") &&
                !car.getName().equals("Ford Pinto") &&
                !car.getName().equals("Yugo GV");
    }
}

Run a Java Microservices Architecture

If you run all of these services with ./mvnw in separate terminal windows, you can navigate to http://localhost:8761 and see they’ve registered with Eureka.

If you navigate to http://localhost:8080/cool-bars in your browser, you’ll be redirected to Okta. What the?

Secure Java Microservices with OAuth 2.0 and OIDC

I’ve already configured security in this microservices architecture using OAuth 2.0 and OIDC. What’s the difference between the two? OIDC is an extension to OAuth 2.0 that provides identity. It also provides discovery so all the different OAuth 2.0 endpoints can be discovered from a single URL (called an issuer).

How did I configure security for all these microservices? I’m glad you asked!

I added Okta’s Spring Boot starter to the pom.xml in api-gateway and car-service:

<dependency>
    <groupId>com.okta.spring</groupId>
    <artifactId>okta-spring-boot-starter</artifactId>
    <version>1.2.0</version>
</dependency>

Then I created a new OIDC app in Okta, configured with authorization code flow. You’ll need to complete the following steps if you want to see everything in action.

Create a Web Application in Okta

From the Applications page, choose Add Application.
On the Create New Application page, select Web.
Give your app a memorable name, add http://localhost:8080/login/oauth2/code/okta as a Login redirect URI, select Refresh Token (in addition to Authorization Code), and click Done.

Copy the issuer (found under API > Authorization Servers), client ID, and client secret into application.properties for both projects.

okta.oauth2.issuer=$issuer
okta.oauth2.client-id=$clientId
okta.oauth2.client-secret=$clientSecret

The Java code in the section below already exists, but I figured I’d explain it so you know what’s going on.

Configure Spring Security for OAuth 2.0 Login and Resource Server

In ApiGatewayApplication.java, I added Spring Security configuration to enable OAuth 2.0 login and enable the gateway as a resource server.

@Configuration
static class OktaOAuth2WebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // @formatter:off
        http
            .authorizeRequests().anyRequest().authenticated()
                .and()
            .oauth2Login()
                .and()
            .oauth2ResourceServer().jwt();
        // @formatter:on
    }
}

The resource server configuration is not used in this example, but I added in case you wanted to hook up a mobile app or SPA to this gateway. If you’re using a SPA, you’ll also need to add a bean to configure CORS.

@Bean
public FilterRegistrationBean<CorsFilter> simpleCorsFilter() {
    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
    CorsConfiguration config = new CorsConfiguration();
    config.setAllowCredentials(true);
    config.setAllowedOrigins(Collections.singletonList("*"));
    config.setAllowedMethods(Collections.singletonList("*"));
    config.setAllowedHeaders(Collections.singletonList("*"));
    source.registerCorsConfiguration("/**", config);
    FilterRegistrationBean<CorsFilter> bean = new FilterRegistrationBean<>(new CorsFilter(source));
    bean.setOrder(Ordered.HIGHEST_PRECEDENCE);
    return bean;
}

NOTE: If you do use a CORS filter like this one, I recommend you change the origins, methods, and headers to be more specific, increasing security.

The CarServiceApplication.java is only configured as a resource server since it’s not expected to be accessed directly.

@Configuration
static class OktaOAuth2WebSecurityConfigurerAdapter extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        // @formatter:off
        http
            .authorizeRequests().anyRequest().authenticated()
                .and()
            .oauth2ResourceServer().jwt();
        // @formatter:on
    }
}

To make it possible for the API gateway to access the Car Service, I created a UserFeignClientInterceptor.java in the API gateway project.

api-gateway/src/main/java/com/example/apigateway/UserFeignClientInterceptor.java

package com.example.apigateway;

import feign.RequestInterceptor;
import feign.RequestTemplate;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClient;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken;
import org.springframework.security.oauth2.core.OAuth2AccessToken;
import org.springframework.stereotype.Component;

@Component
public class UserFeignClientInterceptor implements RequestInterceptor {
    private static final String AUTHORIZATION_HEADER = "Authorization";
    private static final String BEARER_TOKEN_TYPE = "Bearer";
    private final OAuth2AuthorizedClientService clientService;

    public UserFeignClientInterceptor(OAuth2AuthorizedClientService clientService) {
        this.clientService = clientService;
    }

    @Override
    public void apply(RequestTemplate template) {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        OAuth2AuthenticationToken oauthToken = (OAuth2AuthenticationToken) authentication;
        OAuth2AuthorizedClient client = clientService.loadAuthorizedClient(
                oauthToken.getAuthorizedClientRegistrationId(),
                oauthToken.getName());

        OAuth2AccessToken accessToken = client.getAccessToken();
        template.header(AUTHORIZATION_HEADER, String.format("%s %s", BEARER_TOKEN_TYPE, accessToken.getTokenValue()));
    }
}

I configured it as a RequestInterceptor in ApiGatewayApplication.java:

@Bean
public RequestInterceptor getUserFeignClientInterceptor(OAuth2AuthorizedClientService clientService) {
    return new UserFeignClientInterceptor(clientService);
}

And, I added two properties in api-gateway/src/main/resources/application.properties so Feign is Spring Security-aware.

feign.hystrix.enabled=true
hystrix.shareSecurityContext=true

See Java Microservices Running with Security Enabled

Run all of the applications with ./mvnw in separate terminal windows, or in your IDE if you prefer.

TIP: To make it simpler to run in an IDE, there is an aggregator pom.xml in the root directory. If you’d installed IntelliJ IDEA’s command-line launcher, you just need to run idea pom.xml.

Navigate to http://localhost:8080/cool-cars and you’ll be redirected to Okta to log in.

Enter the username and password for your Okta developer account and you should see a list of cool cars.

If you made it this far and got the examples apps running, congratulations! You’re super cool! 😎

Use Netflix Zuul and Spring Cloud to Proxy Routes

Another handy feature you might like in your microservices architecture is Netflix Zuul. Zuul is a gateway service that provides dynamic routing, monitoring, resiliency, and more.

To add Zuul, I added it as a dependency to api-gateway/pom.xml:

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-zuul</artifactId>
</dependency>

Then I added @EnableZuulProxy to the ApiGatewayApplication class.

import org.springframework.cloud.netflix.zuul.EnableZuulProxy;

@EnableZuulProxy
@SpringBootApplication
public class ApiGatewayApplication {
    ...
}

To pass the access token to proxied routes, I created an AuthorizationHeaderFilter class that extends ZuulFilter.

package com.example.apigateway;

import com.netflix.zuul.ZuulFilter;
import com.netflix.zuul.context.RequestContext;
import org.springframework.core.Ordered;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClient;
import org.springframework.security.oauth2.client.OAuth2AuthorizedClientService;
import org.springframework.security.oauth2.client.authentication.OAuth2AuthenticationToken;
import org.springframework.security.oauth2.core.OAuth2AccessToken;
import org.springframework.security.oauth2.core.oidc.OidcUserInfo;

import java.util.Optional;

import static org.springframework.cloud.netflix.zuul.filters.support.FilterConstants.PRE_TYPE;

public class AuthorizationHeaderFilter extends ZuulFilter {

    private final OAuth2AuthorizedClientService clientService;

    public AuthorizationHeaderFilter(OAuth2AuthorizedClientService clientService) {
        this.clientService = clientService;
    }

    @Override
    public String filterType() {
        return PRE_TYPE;
    }

    @Override
    public int filterOrder() {
        return Ordered.LOWEST_PRECEDENCE;
    }

    @Override
    public boolean shouldFilter() {
        return true;
    }

    @Override
    public Object run() {
        RequestContext ctx = RequestContext.getCurrentContext();
        Optional<String> authorizationHeader = getAuthorizationHeader();
        authorizationHeader.ifPresent(s -> ctx.addZuulRequestHeader("Authorization", s));
        return null;
    }

    private Optional<String> getAuthorizationHeader() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        OAuth2AuthenticationToken oauthToken = (OAuth2AuthenticationToken) authentication;
        OAuth2AuthorizedClient client = clientService.loadAuthorizedClient(
                oauthToken.getAuthorizedClientRegistrationId(),
                oauthToken.getName());

        OAuth2AccessToken accessToken = client.getAccessToken();

        if (accessToken == null) {
            return Optional.empty();
        } else {
            String tokenType = accessToken.getTokenType().getValue();
            String authorizationHeaderValue = String.format("%s %s", tokenType, accessToken.getTokenValue());
            return Optional.of(authorizationHeaderValue);
        }
    }
}

NOTE: You might notice that there’s code in the getAuthorizationHeader() method that’s very similar to the code that’s in UserFeignClientInterceptor. Since it’s only a few lines, I opted not to move these to a utility class. The Feign interceptor is for the @FeignClient, while the Zuul filter is for Zuul-proxied requests.

To make Spring Boot and Zuul aware of this filter, I registered it as a bean in the main application class.

public AuthorizationHeaderFilter authHeaderFilter(OAuth2AuthorizedClientService clientService) {
    return new AuthorizationHeaderFilter(clientService);
}

To proxy requests from the API Gateway to the Car Service, I added routes to api-gateway/src/main/resources/application.properties.

zuul.routes.car-service.path=/cars
zuul.routes.car-service.url=http://localhost:8090

zuul.routes.home.path=/home
zuul.routes.home.url=http://localhost:8090

zuul.sensitive-headers=Cookie,Set-Cookie

I added a HomeController to the car-service project for the /home route.

package com.example.carservice;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationToken;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

import java.security.Principal;

@RestController
public class HomeController {

    private final static Logger log = LoggerFactory.getLogger(HomeController.class);

    @GetMapping("/home")
    public String howdy(Principal principal) {
        String username = principal.getName();
        JwtAuthenticationToken token = (JwtAuthenticationToken) principal;
        log.info("claims: " + token.getTokenAttributes());
        return "Hello, " + username;
    }
}

Confirm Your Zuul Routes Work

Since these changes are already in the project you cloned, you should be able to view https://localhost:8080/cars and http://localhost:8080/home in your browser.

What About Spring Cloud Config?

One of the things you might’ve noticed in this example is you had to configure the OIDC properties in each application. This could be a real pain if you had 500 microservices. Yes, you could define them as environment variables and this would solve the problem. However, if you have different microservices stacks using different OIDC client IDs, this approach will be difficult.

Spring Cloud Config is a project that provides externalized configuration for distributed systems. Rather than adding it to this example, I’ll cover it in a future tutorial.

What About Kotlin?

I wrote this post with Java because it’s the most popular language in the Java ecosystem. However, Kotlin is on the rise, according to RedMonk’s programming language rankings from January 2019.

For this quarter, at least, Kotlin grew substantially while all three of its fellow JVM-based counterparts declined. Kotlin jumped so far, in fact, that it finally broke into the Top 20 at #20 and leapfrogged Clojure (#24) and Groovy (#24) while doing so. It’s still well behind Scala (#13), but Kotlin’s growth has been second only to Swift in this history of these rankings so it will be interesting to see what lies ahead in the next run or two.

Spring has excellent support for Kotlin, and you can choose it as a language on start.spring.io. If you’d like to see us write more posts using Kotlin, please let us know in the comments!

Known Issues with Refresh Tokens

By default, Okta’s access tokens expire after one hour. This is expected, and short-lived access tokens are recommended when using OAuth 2.0. Refresh tokens typically live a lot longer — think days or months — and can be used to get new access tokens. This should happen automatically when using Okta’s Spring Boot starter, but it does not.

I configured my Okta org so its access tokens expire in five minutes. You can do this by going to API > Authorization Servers > Access Policies , click on the Default Policy , and edit its rule. Then change the access token lifetime from 1 hour to 5 minutes.

Hit http://localhost:8080/cool-cars in your browser and you’ll be redirected to Okta to login. Log in and you should see a JSON string of cars.

Go do something else for more than 5 minutes.

Come back, refresh your browser and you’ll see [] instead of all the cars.

Update: Spring Security 5.1 doesn’t yet automatically refresh the OAuth access token. It should be available in Spring Security 5.2.

Have More Fun with Spring Boot, Spring Cloud, and Microservices

I hope you liked this tour of how to build Java microservice architectures with Spring Boot and Spring Cloud. You learned how to build everything with minimal code, then configure it to be secure with Spring Security, OAuth 2.0, and Okta.

You can find all the code shown in this tutorial on GitHub.

We’re big fans of Spring Boot, Spring Cloud, and microservices on this blog. Here are several other posts you might find interesting:

Please follow us on Twitter @oktadev and subscribe to our YouTube channel for more Spring Boot and microservices knowledge.

DEV Community: Matt Raible

A Delightful Trip to Devnexus

Tuesday, April 9

Wednesday, April 10

Thursday, April 11

Friday, April 12

Funemployment 2024

Java Microservices with Spring Boot and Spring Cloud

Create Java Microservices with Spring Boot and Spring Cloud

Run a Secure Spring Boot Microservice Architecture

My Developer Story with Spring Boot and Spring Cloud

Service Discovery with Netflix Eureka

Build a Java Microservice with Spring Data REST

Connect to Java Microservices with Spring Cloud OpenFeign

Add Routing with Spring Cloud Gateway

Proxy Requests by Path with Spring MVC

Proxy Requests by Path with WebFlux

Secure Spring Boot Microservices with OAuth 2.0 and OIDC

Fetch an Access Token as a JWT

Spring Cloud Gateway MVC and OAuth 2.0

Spring Boot Microservices and Refresh Tokens

The Okta Spring Boot starter and Keycloak

Stay secure with Spring Boot and Spring Cloud!

Build a Beautiful CRUD App with Spring Boot and Angular

Configure and Run a Spring Boot and Angular App

Verify Cypress end-to-end tests pass

Create a Java REST API with Spring Boot

Add a JPA domain model

Create an Angular App with the Angular CLI

Call your Spring Boot API and display the results

Build an Angular GroupList component

Build an Angular GroupEdit component

Secure Spring Boot with OpenID Connect and OAuth

Configure Spring Security for maximum protection

Update Angular to handle CSRF and be identity-aware

Update your Angular app's authentication mechanism

Configure Maven to Package Angular with Spring Boot

Verify Everything Works with Cypress

Fix Unit Tests

Use GitHub Actions to Build and Test Your App

Build Something Fabulous with Spring Boot and Angular!

Micro Frontends for Java Microservices

Java microservices with Spring Boot and JHipster

A quick introduction to Module Federation

Why should Java developers care?

Micro frontends in action with JHipster

Micro frontend options: Angular, React, and Vue

Build Java microservices with Spring Boot and WebFlux

Run your reactive Spring Boot microservices

Zero turnaround development that sparks joy

A look under the hood of micro frontends

Build and run with Docker

Switch identity providers

Deploy with Kubernetes

Learn more about micro frontends and microservices

Use React and Spring Boot to Build a Simple CRUD App

Create an API app with Spring Boot

Add a JPA domain model

Create a React UI with Create React App

Call your Spring Boot API and display the results

Build a React GroupList component

Add a React GroupEdit component

Add authentication with Okta

Spring Security + OIDC

Create an OIDC app in Okta

What does the Okta CLI do?

Use Auth0 for OIDC

Configure Spring Security for React and user identity

Modify React to handle CSRF and be identity-aware

Configure Maven to build and package React with Spring Boot

Learn more about Spring Boot and React

Build Secure Ionic Apps with Angular and JHipster

What the heck is JHipster?

✨ Introducing the JHipster Ionic blueprint!

Build a mobile app with Ionic and Angular

How to integrate Ionic and Spring Boot

Run your Spring Boot API

Run your Ionic app

Run your Ionic app on iOS using Capacitor

Run your Ionic app on Android

Build an Angular `GroupList` component

Build an Angular `GroupEdit` component

Build a React `GroupList` component

Add a React `GroupEdit` component